Cleanup of documentation configuration (#3448)

docs/conf.py

@@ -36,7 +36,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
-    "sphinxcontrib.napoleon",
+    "sphinx.ext.napoleon",
     "myst_parser",
     "sphinx_js",
     "sphinx_click",
@@ -87,9 +87,6 @@ source_suffix = [".rst", ".md"]
 # The master toctree document.
 master_doc = "index"
 
-# The language for content autogenerated by Sphinx.
-language = None
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
@@ -98,7 +95,7 @@ exclude_patterns = [
     ".DS_Store",
     "README.md",
     "sphinx_pyodide",
-    ".venv",
+    ".*",
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -137,6 +134,11 @@ epub_exclude_files = ["search.html"]
 
 
 def delete_attrs(cls):
+    """Prevent attributes of a class or module from being documented.
+
+    The top level documentation comment of the class or module will still be
+    rendered.
+    """
     for name in dir(cls):
         if not name.startswith("_"):
             try:
@@ -206,14 +208,6 @@ if IN_SPHINX:
 
     import micropip  # noqa: F401
     import pyodide
-
-    # We hacked it so that autodoc will look for submodules, but only if we import
-    # them here. TODO: look these up in the source directory?
-    import pyodide.code
-    import pyodide.console
-    import pyodide.ffi.wrappers
-    import pyodide.http
-    import pyodide.webloop
     from pyodide.ffi import JsProxy
 
     del JsProxy.__new__
@@ -242,6 +236,9 @@ if IN_SPHINX:
 
     # Prevent API docs for webloop methods: they are the same as for base event loop
     # and it clutters api docs too much
+    import pyodide.console
+    import pyodide.webloop
+
     delete_attrs(pyodide.webloop.WebLoop)
     delete_attrs(pyodide.webloop.WebLoopPolicy)
     delete_attrs(pyodide.console.PyodideConsole)
@@ -260,21 +257,6 @@ def globalReplace(app, docname, source):
 
 global_replacements = {"{{PYODIDE_CDN_URL}}": CDN_URL}
 
-# Add extra CSS classes to some documentation fields. We use this in pyodide.css
-# to fix the rendering of autodoc return value annotations.
-from sphinx.util.docfields import Field
-
-orig_make_field = Field.make_field
-
-
-def make_field(self, *args, **kwargs):
-    node = orig_make_field(self, *args, **kwargs)
-    node["classes"].append(self.name)
-    return node
-
-
-Field.make_field = make_field
-
 
 def typehints_formatter(annotation, config):
     """Adjust the rendering of Literal types.

docs/requirements-doc.txt

@@ -5,7 +5,6 @@ packaging   # required by micropip at import time
 sphinx>=4.4.0
 sphinx-argparse-cli~=1.6.0
 sphinx_book_theme
-sphinxcontrib-napoleon>=0.7
 sphinx-issues==2.0.0
 sphinx-js==3.2.1
 sphinx-version-warning~=1.1.2

docs/sphinx_pyodide/sphinx_pyodide/__init__.py

@@ -1,4 +1,3 @@
-from .autodoc_submodules import monkeypatch_module_documenter
 from .jsdoc import (
     PyodideAnalyzer,
     get_jsdoc_content_directive,
@@ -42,9 +41,26 @@ def patch_templates():
     JsRenderer.rst = patched_rst_method
 
 
+def patch_field():
+    """
+    Add extra CSS classes to some documentation fields. We use this in
+    pyodide.css to fix the rendering of autodoc return value annotations.
+    """
+    from sphinx.util.docfields import Field
+
+    orig_make_field = Field.make_field
+
+    def make_field(self, *args, **kwargs):
+        node = orig_make_field(self, *args, **kwargs)
+        node["classes"].append(self.name)
+        return node
+
+    Field.make_field = make_field
+
+
 def setup(app):
     patch_templates()
-    monkeypatch_module_documenter()
+    patch_field()
     app.add_lexer("pyodide", PyodideLexer)
     app.add_lexer("html-pyodide", HtmlPyodideLexer)
     app.setup_extension("sphinx_js")

docs/sphinx_pyodide/sphinx_pyodide/autodoc_submodules.py

@@ -1,73 +0,0 @@
-"""
-Monkey patch autodoc to recursively include submodules as well. We have to
-import the submodules for it to find them.
-"""
-
-from typing import Any
-
-from sphinx.ext.autodoc import ModuleDocumenter, ObjectMember
-from sphinx.util.inspect import safe_getattr
-
-__all__ = ["monkeypatch_module_documenter"]
-
-
-def get_module_members(module: Any) -> list[tuple[str, Any]]:
-    members: dict[str, tuple[str, Any]] = {}
-    for name in dir(module):
-        try:
-            value = safe_getattr(module, name, None)
-            # Before patch this used to always do
-            # members[name] = (name, value)
-            # We want to also recursively look up names on submodules.
-            if type(value).__name__ != "module":
-                members[name] = (name, value)
-                continue
-            if name.startswith("_"):
-                continue
-            submodule = value  # Rename for clarity
-            [base, _, rest] = submodule.__name__.partition(".")
-            if not base == module.__name__:
-                # Not part of package, don't document
-                continue
-
-            for (sub_name, sub_val) in get_module_members(submodule):
-                # Skip names not in __all__
-                if hasattr(submodule, "__all__") and sub_name not in submodule.__all__:
-                    continue
-                qual_name = rest + "." + sub_name
-                members[qual_name] = (qual_name, sub_val)
-            continue
-        except AttributeError:
-            continue
-
-    return sorted(list(members.values()))
-
-
-def get_object_members(
-    self: ModuleDocumenter, want_all: bool
-) -> tuple[bool, list[tuple[str, Any]] | list[ObjectMember]]:
-    """
-    For some reason I was unable to monkey patch get_module_members so we monkey
-    patch get_object_members to call our updated `get_module_members`.
-
-    This is similar to the original function but I dropped the `want_all` branch
-    for brevity because we don't use it.
-    """
-    members = get_module_members(self.object)
-    if not self.__all__:
-        # for implicit module members, check __module__ to avoid
-        # documenting imported objects
-        return True, members
-    else:
-        ret = []
-        for name, value in members:
-            if name in self.__all__ or "." in name:
-                ret.append(ObjectMember(name, value))
-            else:
-                ret.append(ObjectMember(name, value, skipped=True))
-
-        return False, ret
-
-
-def monkeypatch_module_documenter():
-    ModuleDocumenter.get_object_members = get_object_members

src/py/_pyodide/_core_docs.py

@@ -108,7 +108,7 @@ class JsProxy(metaclass=_JsProxyMetaClass):
         key on JavaScript object identity.
 
         If two `JsProxy` are made with the same backing JavaScript object, they
-        will have the same `js_id`. The reault is a "pseudorandom" 32 bit integer.
+        will have the same `js_id`.
         """
         return 0