docs: module inclusion policy (#119)

* docs: module inclusion policy

* module-policy: typo

Author: woodruffw

docs/conf.py

@@ -30,6 +30,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
 ]
 
 html_theme = "furo"

docs/index.rst

@@ -19,6 +19,7 @@ Contents
 
    install
    usage
+   module-policy
 
 
 Indices and tables

docs/module-policy.rst

@@ -0,0 +1,49 @@
+Module inclusion policy
+=======================
+
+Python is a dynamic language with a complex module system, including
+modules that are created only at runtime or appear on specific
+supported platforms.
+
+This page exists to document ``stdlib-list``'s approach to module detection
+and subsequent inclusion. It is not intended to be permanent, and may change
+over time as Python itself changes (or our approach to module detection
+improves).
+
+Current guiding rules
+---------------------
+
+* Missing top-level modules **are a bug**: if a new version of Python adds a new
+  top-level module, our failure to detect it should be considered a bug.
+
+  Concretely: if ``examplemodule`` is present in Python 3.999, then it should be
+  included in the ``stdlib_list("3.999")`` listing.
+
+* Missing sub-modules are **best-effort**: if ``examplemodule`` contains
+  ``examplemodule.foo.bar.baz.deeply.nested``, we make a best-effort attempt
+  to detect each inner module but make no guarantee about doing so.
+
+  Our rationale for this is that "stdlib-ness" is inherited from the parent
+  module, even when not explicitly listed. In other words: anything that matches
+  ``examplemodule.*`` is in the standard library by definition so long
+  as ``examplemodule`` is in the standard library.
+
+* Platform-specific modules are **best-effort**: ``stdlib-list`` is currently collected
+  from Linux builds of CPython. This means that Windows- and macOS-specific modules
+  (i.e., modules that aren't installed except for on those hosts) are not necessarily
+  included.
+
+  This includes top-level modules.
+
+* Missing non-CPython modules are **not supported**: ``stdlib-list`` is implicitly
+  a list of CPython's standard library modules, which are expected to be mirrored
+  in other implementations of Python.
+
+* Psuedo-modules are **not supported**: Python sometimes makes use of
+  "pesudo-modules", i.e. namespaces placed into ``sys.modules`` that don't
+  pass :py:func:`inspect.ismodule`. We don't currently support these, since the
+  semantics for doing so are unclear.
+  See `stdlib-list#117 <https://github.com/pypi/stdlib-list/issues/117>`__
+  for additional details.
+
+If you have a scenario not covered by the rules above, please file an issue!