diff --git a/docs/conf.py b/docs/conf.py index 77edead02..d72371f2e 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 13fcd4daa..1a0a7dcd4 100644 --- a/docs/requirements-doc.txt +++ b/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 diff --git a/docs/sphinx_pyodide/sphinx_pyodide/__init__.py b/docs/sphinx_pyodide/sphinx_pyodide/__init__.py index fff751a77..8499d647b 100644 --- a/docs/sphinx_pyodide/sphinx_pyodide/__init__.py +++ b/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") diff --git a/docs/sphinx_pyodide/sphinx_pyodide/autodoc_submodules.py b/docs/sphinx_pyodide/sphinx_pyodide/autodoc_submodules.py deleted file mode 100644 index 865cb93e0..000000000 --- a/docs/sphinx_pyodide/sphinx_pyodide/autodoc_submodules.py +++ /dev/null @@ -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 diff --git a/src/py/_pyodide/_core_docs.py b/src/py/_pyodide/_core_docs.py index b554613a2..6dc057499 100644 --- a/src/py/_pyodide/_core_docs.py +++ b/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