Add ADR

Author: coretl

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.