From 6301a022c05e3f89ab64b273467c87f69e44068b Mon Sep 17 00:00:00 2001
From: Gary Yendell <gary.yendell@diamond.ac.uk>
Date: Fri, 12 Jul 2024 15:00:37 +0000
Subject: [PATCH] Use autodoc2 for API docs

---
 .gitignore            |  1 +
 docs/conf.py          | 34 ++++++++++++++++++++++++++++++----
 docs/reference/api.md | 13 +++----------
 pyproject.toml        |  1 +
 src/pvi/device.py     |  8 ++++----
 5 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/.gitignore b/.gitignore
index ab6ebeeb..c4c767e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -58,6 +58,7 @@ cov.xml
 
 # Sphinx documentation
 docs/_build/
+docs/reference/_api
 
 # PyBuilder
 target/
diff --git a/docs/conf.py b/docs/conf.py
index 0d72a592..943f5f06 100644
--- a/docs/conf.py
+++ b/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
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 45658678..b7976535 100644
--- a/docs/reference/api.md
+++ b/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
 ```
diff --git a/pyproject.toml b/pyproject.toml
index 542c1c35..3077a4ad 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -42,6 +42,7 @@ dev = [
     "sphinx-autobuild",
     "sphinx-copybutton",
     "sphinx-design",
+    "sphinx-autodoc2",
     "tox-direct",
     "types-mock",
 ]
diff --git a/src/pvi/device.py b/src/pvi/device.py
index 572c3459..ee8b0197 100644
--- a/src/pvi/device.py
+++ b/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:]