📚 DOCS: Use sphinx-autodoc2 for API (#704)

This will allow moving source docstrings to use MyST instead of rST 🎉

Author: chrisjsewell

codecov.yml

@@ -6,5 +6,5 @@ coverage:
         threshold: 0.5%
     patch:
       default:
-        target: 75%
+        target: 60%
         threshold: 0.5%

docs/api/reference.rst

@@ -28,9 +28,10 @@
 # ones.
 extensions = [
     "myst_parser",
-    "sphinx.ext.autodoc",
+    "autodoc2",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc",
     "sphinx_design",
     "sphinxext.rediraffe",
     "sphinxcontrib.mermaid",
@@ -57,30 +58,27 @@
 
 # -- Autodoc settings ---------------------------------------------------
 
-autodoc_member_order = "bysource"
+autodoc2_packages = ["../myst_parser"]
+autodoc2_hidden_objects = ["dunder", "private", "inherited"]
+autodoc2_replace_annotations = [
+    ("re.Pattern", "typing.Pattern"),
+    ("markdown_it.MarkdownIt", "markdown_it.main.MarkdownIt"),
+]
+autodoc2_replace_bases = [
+    ("myst_parser._compat.Protocol", "typing.Protocol"),
+    ("myst_parser._compat.TypedDict", "typing.TypedDict"),
+    ("sphinx.directives.SphinxDirective", "sphinx.util.docutils.SphinxDirective"),
+]
 nitpicky = True
+nitpick_ignore_regex = [
+    (r"py:.*", r"docutils\..*"),
+]
 nitpick_ignore = [
-    ("py:class", "docutils.nodes.document"),
-    ("py:class", "docutils.nodes.docinfo"),
-    ("py:class", "docutils.nodes.Element"),
-    ("py:class", "docutils.nodes.Node"),
-    ("py:class", "docutils.nodes.field_list"),
-    ("py:class", "docutils.nodes.problematic"),
-    ("py:class", "docutils.nodes.pending"),
-    ("py:class", "docutils.nodes.system_message"),
-    ("py:class", "docutils.statemachine.StringList"),
-    ("py:class", "docutils.parsers.rst.directives.misc.Include"),
-    ("py:class", "docutils.parsers.rst.Parser"),
-    ("py:class", "docutils.utils.Reporter"),
-    ("py:class", "nodes.Element"),
-    ("py:class", "nodes.Node"),
-    ("py:class", "nodes.system_message"),
-    ("py:class", "Directive"),
-    ("py:class", "Include"),
-    ("py:class", "StringList"),
-    ("py:class", "DocutilsRenderer"),
-    ("py:class", "MockStateMachine"),
+    ("py:obj", "myst_parser._docs._ConfigBase"),
     ("py:exc", "MarkupError"),
+    ("py:class", "sphinx.util.typing.Inventory"),
+    ("py:class", "sphinx.writers.html.HTMLTranslator"),
+    ("py:obj", "sphinx.transforms.post_transforms.ReferencesResolver"),
 ]
 
 # -- MyST settings ---------------------------------------------------
@@ -166,6 +164,7 @@
     "sphinx/intro.md": "intro.md",
     "using/use_api.md": "api/index.md",
     "api/index.md": "api/reference.rst",
+    "api/reference.rst": "apidocs/index.md",
     "using/syntax.md": "syntax/syntax.md",
     "using/syntax-optional.md": "syntax/optional.md",
     "using/reference.md": "syntax/reference.md",

docs/conf.py

@@ -59,7 +59,7 @@ stylesheet-dirs: path/to/html5_polyglot/
 stylesheet-path: minimal.css, responsive.css
 ```
 
-You can also use the {py:class}`myst_parser.docutils_.Parser` class programmatically with the [Docutils publisher API](https://docutils.sourceforge.io/docs/api/publisher.html):
+You can also use the {py:class}`myst_parser.parsers.docutils_.Parser` class programmatically with the [Docutils publisher API](https://docutils.sourceforge.io/docs/api/publisher.html):
 
 ```python
 from docutils.core import publish_string

docs/docutils.md

@@ -118,6 +118,7 @@ However, the special [`eval-rst` directive](syntax/directives/parsing) can be us
 .. autoclass:: myst_parser.mocking.MockRSTParser
     :show-inheritance:
     :members: parse
+    :noindex:
 ```
 
 As with other objects in MyST, this can then be referenced:

docs/faq/index.md

@@ -148,7 +148,7 @@ develop/index.md
 develop/_changelog.md
 syntax/reference
 develop/background.md
-api/reference.rst
+apidocs/index.rst
 ```
 
 [commonmark]: https://commonmark.org/

docs/index.md

@@ -43,22 +43,22 @@ def __call__(
         ...
 
 
-def instance_of(type: type[Any] | tuple[type[Any], ...]) -> ValidatorType:
+def instance_of(type_: type[Any] | tuple[type[Any], ...]) -> ValidatorType:
     """
     A validator that raises a `TypeError` if the initializer is called
     with a wrong type for this particular attribute (checks are performed using
     `isinstance` therefore it's also valid to pass a tuple of types).
 
-    :param type: The type to check for.
+    :param type_: The type to check for.
     """
 
     def _validator(inst, field, value, suffix=""):
         """
         We use a callable class to be able to change the ``__repr__``.
         """
-        if not isinstance(value, type):
+        if not isinstance(value, type_):
             raise TypeError(
-                f"'{field.name}{suffix}' must be of type {type!r} "
+                f"'{field.name}{suffix}' must be of type {type_!r} "
                 f"(got {value!r} that is a {value.__class__!r})."
             )
 

myst_parser/config/dc_validators.py

@@ -1,4 +1,6 @@
-"""A module for compatibility with the docutils>=0.17 `include` directive, in RST documents::
+"""A module for compatibility with the docutils>=0.17 `include` directive, in RST documents:
+
+For example::
 
    .. include:: path/to/file.md
       :parser: myst_parser.docutils_

myst_parser/docutils_.py

@@ -43,7 +43,7 @@ class InventoryType(TypedDict):
     version: str
     """The version of the project."""
     base_url: str | None
-    """The base URL of the `loc`s."""
+    """The base URL of the `loc`."""
     objects: dict[str, dict[str, dict[str, InventoryItemType]]]
     """Mapping of domain -> object type -> name -> item."""
 

myst_parser/inventory.py

@@ -1 +1,8 @@
-"""Conversion of Markdown-it tokens to docutils AST."""
+"""Conversion of Markdown-it tokens to docutils AST.
+
+These renderers take the markdown-it parsed token stream
+and convert it to the docutils AST.
+The sphinx renderer is a subclass of the docutils one,
+with some additional methods only available
+*via* sphinx e.g. multi-document cross-referencing.
+"""