Update sphinx multimethod customization to handle toplevel functions (#1932)

* Update sphinx multimethod customization to handle toplevel functions

* Use sphinx 9.0

* Resolve sphinx warnings

* Update sphinx to 9.1.0

Author: lorenzncode

doc/classreference.rst

@@ -30,11 +30,11 @@ Topological Classes
     Shape
     Vertex
     Edge
-    cadquery.occ_impl.shapes.Mixin1D
+    occ_impl.shapes.Mixin1D
     Wire
     Face
     Shell
-    cadquery.occ_impl.shapes.Mixin3D
+    occ_impl.shapes.Mixin3D
     Solid
     Compound
 

doc/conf.py

@@ -36,13 +36,13 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    "sphinx.ext.autodoc",
+    #    "sphinx.ext.autodoc",
+    #    "sphinx.ext.autosummary",
+    "sphinx_autodoc_multimethod",  # custom extension; includes autodoc and autosummary
     "sphinx.ext.viewcode",
-    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "cadquery.cq_directive",
     "sphinx.ext.mathjax",
-    "sphinx_autodoc_multimethod",
 ]
 
 autodoc_typehints = "both"
@@ -293,29 +293,6 @@
 # texinfo_show_urls = 'footnote'
 
 
-patparam = re.compile(r"(\W*):\W*param.*")
-
-
-def process_docstring_insert_self(app, what, name, obj, options, lines):
-    """
-    Insert self in front of documented params for instance methods
-    """
-
-    if (
-        what == "method"
-        and app.config.autodoc_typehints in ("both", "description")
-        and app.config.autodoc_typehints_description_target in ("all")
-        and getattr(obj, "__self__", None) is None
-        and "self" in obj.__annotations__
-    ):
-        for i, line in enumerate(lines):
-            if m := patparam.match(line):
-                indent = m.group(1)
-                lines.insert(i, f"{indent}:param self:")
-                break
-
-
 def setup(app):
 
     app.add_css_file("tables.css")
-    app.connect("autodoc-process-docstring", process_docstring_insert_self)

doc/ext/sphinx_autodoc_multimethod.py

@@ -0,0 +1,20 @@
+import sphinx.ext.autodoc
+
+# see sphinx/ext/autodoc/_dynamic/_signatures.py
+from ._dynamic._signatures import _format_signatures
+from .process_docstring_multimethod import process_docstring_multimethod
+
+from .autosummary_multimethod import MultimethodAutosummary
+
+sphinx.ext.autodoc._dynamic._loader._format_signatures = _format_signatures
+
+
+def setup(app):
+
+    app.setup_extension("sphinx.ext.autodoc")
+    app.connect("autodoc-process-docstring", process_docstring_multimethod)
+
+    app.setup_extension("sphinx.ext.autosummary")
+    app.add_directive("autosummary", MultimethodAutosummary, override=True)
+
+    return {"parallel_read_safe": True, "parallel_write_safe": True}