Use autodoc2 for API docs

.gitignore

@@ -58,6 +58,7 @@ cov.xml
 
 # Sphinx documentation
 docs/_build/
+docs/reference/_api
 
 # PyBuilder
 target/

docs/conf.py

@@ -30,8 +30,8 @@
     version = release
 
 extensions = [
-    # Use this for generating API docs
-    "sphinx.ext.autodoc",
+    # Autodoc2 for generating API docs from docstrings
+    "autodoc2",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -49,7 +49,18 @@
 ]
 
 # So we can use the ::: syntax
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = [
+    "colon_fence",
+    "fieldlist",
+]
+
+# Autodoc2 Config
+autodoc2_packages = [
+    "../src/pvi",
+]
+autodoc2_render_plugin = "myst"
+autodoc2_output_dir = "reference/_api"
+# autodoc2_annotations = False
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
@@ -67,7 +78,21 @@
     ("py:class", "'bool'"),
     ("py:class", "'object'"),
     ("py:class", "'id'"),
-    ("py:class", "typing_extensions.Literal"),
+    ("py:class", "typing.Literal"),
+    ("py:class", f"{project}._version.VERSION_TUPLE"),
+]
+nitpick_ignore_regex = [
+    ("py:obj", "pydantic.*"),
+    ("py:class", "pydantic.*"),
+    ("py:obj", "lxml.*"),
+    ("py:class", "lxml.*"),
+    ("py:class", "typing_extensions.*"),
+    ("py:obj", r"typing.Annotated\[.*"),
+    ("py:class", r".*\.T"),
+    ("py:class", r"pvi\.device\..*Union"),
+    ("py:class", ".*.?Tree"),
+    ("py:class", ".*.PascalStr"),
+    ("py:class", ".*.Cls"),
 ]
 
 # Both the class’ and the __init__ method’s docstring are concatenated and
@@ -167,6 +192,7 @@
         }
     ],
     "navigation_with_keys": False,
+    "show_toc_level": 3,
 }
 
 # A dictionary of values to pass into the template engine’s context for all pages

docs/reference/api.md

@@ -1,17 +1,10 @@
 # API
 
-```{eval-rst}
-.. automodule:: pvi
-
-    ``pvi``
-    -------
-```
-
 This is the internal API reference for pvi
 
 ```{eval-rst}
-.. data:: pvi.__version__
-    :type: str
+.. toctree::
+   :maxdepth: 1
 
-    Version number as calculated by https://github.com/pypa/setuptools_scm
+   _api/index
 ```

pyproject.toml

@@ -42,6 +42,7 @@ dev = [
     "sphinx-autobuild",
     "sphinx-copybutton",
     "sphinx-design",
+    "sphinx-autodoc2",
     "tox-direct",
     "types-mock",
 ]

src/pvi/device.py

@@ -32,10 +32,10 @@
 def to_title_case(pascal_s: str) -> str:
     """Takes a PascalCaseFieldName and returns an Title Case Field Name
 
-    Args:
-        pascal_s: E.g. PascalCaseFieldName
-    Returns:
-        Title Case converted name. E.g. Pascal Case Field Name
+    :param pascal_s: e.g. PascalCaseFieldName
+
+    :returns: Title Case converted name. E.g. Pascal Case Field Name
+
     """
     return PASCAL_CASE_REGEX.sub(lambda m: " " + m.group(), pascal_s)[1:]