Use autosummary for sphinx docs (#194)

Author: coretl

.gitignore

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

docs/explanations/decisions/0019-autosummary-api-docs.md

@@ -0,0 +1,23 @@
+# 19. Use autosummary to create API docs
+
+Date: 2024-09-10
+
+## Status
+
+Accepted
+
+## Context
+
+The current sphinx API documentation requires you to paste automodule directives in for each subpackage. This is counter intuitive and also places all the docs on one page. People saw a blank page and assumed API generation was broken.
+
+Using autosummary would give a nicer summary, but requires pasting custom templates in which makes sphinx-autobuild keep reloading forever.
+
+Using autodoc2 would allow md docstrings, but doesn't work with pydantic, and doesn't support google or numpy docstrings.
+
+## Decision
+
+Decided to use autosummary, with one page per subpackage. This means at most 2 reloads of sphinx-autobuild before it settles, which is reasonable.
+
+## Consequences
+
+Try to push a bit of the custom template (generating public_members in member order) up to sphinx.

template/.gitignore

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

template/README.md.jinja

@@ -31,8 +31,8 @@ Or if it is a commandline tool then you might put some example commands here:
 
 ```
 python -m {{package_name}} --version
-```
-{% if sphinx %}
+```{% if sphinx %}
+
 <!-- README only content. Anything below this line won't be included in index.md -->
 
 See {{docs_url}} for more detailed documentation.{% endif %}

template/src/{{ package_name }}/__init__.py

@@ -1,3 +1,11 @@
+"""Top level API.
+
+.. data:: __version__
+    :type: str
+
+    Version number as calculated by https://github.com/pypa/setuptools_scm
+"""
+
 from ._version import __version__
 
 __all__ = ["__version__"]

template/src/{{ package_name }}/__main__.py.jinja

@@ -1,4 +1,5 @@
 """Interface for ``python -m {{package_name}}``."""
+
 from argparse import ArgumentParser
 from collections.abc import Sequence
 

template/{% if sphinx %}docs{% endif %}/_api.rst.jinja

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for {{ package_name }} and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    {{ package_name }}

template/{% if sphinx %}docs{% endif %}/_templates/custom-module-template.rst

@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+    {%- if item in functions + classes + exceptions + attributes %}
+        {% set _ = filtered_members.append(item) %}
+    {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Submodules
+
+    .. autosummary::
+        :toctree:
+        :template: custom-module-template.rst
+        :recursive:
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block members %}
+    {% if filtered_members %}
+    .. rubric:: Members
+
+    .. autosummary::
+        :nosignatures:
+    {% for item in filtered_members %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

template/{% if sphinx %}docs{% endif %}/conf.py.jinja

@@ -33,6 +33,8 @@ else:
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    # and making summary tables at the top of API docs
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -81,6 +83,12 @@ autodoc_member_order = "bysource"
 # Don't inherit docstrings from baseclasses
 autodoc_inherit_docstrings = False
 
+# Document only what is in __all__
+autosummary_ignore_module_all = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # Output graphviz directive produced images in a scalable format
 graphviz_output_format = "svg"
 

template/{% if sphinx %}docs{% endif %}/reference.md.jinja

@@ -6,7 +6,7 @@ Technical reference material including APIs and release notes.
 :maxdepth: 1
 :glob:
 
-reference/*
+API <_api/{{ package_name }}>
 genindex
 Release Notes <{{ repo_url }}/releases>
 ```