Update docs to use autosummary for API reference

.gitignore

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

docs/conf.py

@@ -32,6 +32,7 @@
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -48,6 +49,10 @@
     "myst_parser",
 ]
 
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # So we can use the ::: syntax
 myst_enable_extensions = ["colon_fence"]
 
@@ -93,7 +98,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # These patterns also affect html_static_path and html_extra_path
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "_templates"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

docs/reference/api.md

@@ -1,17 +1,41 @@
 # API
 
+This is the internal API reference for fastcs. The key modules are summarised below.
+
+## Controllers
+
 ```{eval-rst}
-.. automodule:: fastcs
+.. automodule:: fastcs.controller
+    :members:
+    :no-index:
+```
 
-    ``fastcs``
-    -----------------------------------
+## Attributes
+
+```{eval-rst}
+.. automodule:: fastcs.attributes
+    :members:
+    :no-index:
 ```
 
-This is the internal API reference for fastcs
+## Datatypes
 
 ```{eval-rst}
-.. data:: fastcs.__version__
-    :type: str
+.. automodule:: fastcs.datatypes
+    :members:
+    :no-index:
+```
+
+## Auto Summary
+
+The full API reference is available here:
+
+```{eval-rst}
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
 
-    Version number as calculated by https://github.com/pypa/setuptools_scm
+   fastcs
 ```

src/fastcs/attributes.py

@@ -7,7 +7,7 @@
 
 
 class AttrMode(Enum):
-    """Access mode of an `Attribute`."""
+    """Access mode of an ``Attribute``."""
 
     READ = 1
     WRITE = 2
@@ -16,15 +16,15 @@ class AttrMode(Enum):
 
 @runtime_checkable
 class Sender(Protocol):
-    """Protocol for setting the value of an `Attribute`."""
+    """Protocol for setting the value of an ``Attribute``."""
 
     async def put(self, controller: Any, attr: AttrW, value: Any) -> None:
         pass
 
 
 @runtime_checkable
 class Updater(Protocol):
-    """Protocol for updating the cached readback value of an `Attribute`."""
+    """Protocol for updating the cached readback value of an ``Attribute``."""
 
     update_period: float
 
@@ -34,15 +34,15 @@ async def update(self, controller: Any, attr: AttrR) -> None:
 
 @runtime_checkable
 class Handler(Sender, Updater, Protocol):
-    """Protocol encapsulating both `Sender` and `Updater`."""
+    """Protocol encapsulating both ``Sender`` and ``Updater``."""
 
     pass
 
 
 class Attribute(Generic[T]):
     """Base FastCS attribute.
 
-    Instances of this class added to a `Controller` will be used by the backend.
+    Instances of this class added to a ``Controller`` will be used by the backend.
     """
 
     def __init__(
@@ -77,7 +77,7 @@ def group(self) -> str | None:
 
 
 class AttrR(Attribute[T]):
-    """A read-only `Attribute`."""
+    """A read-only ``Attribute``."""
 
     def __init__(
         self,
@@ -109,7 +109,7 @@ def updater(self) -> Updater | None:
 
 
 class AttrW(Attribute[T]):
-    """A write-only `Attribute`."""
+    """A write-only ``Attribute``."""
 
     def __init__(
         self,
@@ -148,7 +148,7 @@ def sender(self) -> Sender | None:
 
 
 class AttrRW(AttrW[T], AttrR[T]):
-    """A read-write `Attribute`."""
+    """A read-write ``Attribute``."""
 
     def __init__(
         self,

src/fastcs/controller.py

@@ -26,9 +26,9 @@ class Controller(BaseController):
     """Top-level controller for a device.
 
     This is the primary class for implementing device support in FastCS. Instances of
-    this class can be loaded into a backend to access its `Attribute`s. The backend can
-    then perform a specific function with the set of `Attributes`, such as generating a
-    UI or creating parameters for a control system.
+    this class can be loaded into a backend to access its ``Attribute``s. The backend
+    can then perform a specific function with the set of ``Attributes``, such as
+    generating a UI or creating parameters for a control system.
     """
 
     def __init__(self) -> None: