feat: add Sphinx documentation scaffolding to template

template/.github/workflows/cicd.yaml

@@ -51,3 +51,17 @@ jobs:
         run: uv sync --no-sources
       - name: Run pytest
         run: uv run --no-sources pytest
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build documentation (strict)
+        run: make docs-strict
+      - name: Run docs drift tests
+        run: make test-docs

template/Makefile

@@ -42,3 +42,61 @@ pre_commit:
 format:
 	# format all code
 	uv run ruff format
+
+# ---------------------------------------------------------------------------
+# Documentation targets — merged into the project Makefile by the
+# update-docs skill. Assumes Sphinx source is at docs/source/ and output
+# lands at docs/build/.
+#
+# This header also serves as the merge sentinel: the scaffolding step looks
+# for it in the project Makefile to detect that the block was already merged
+# (idempotency). Keep the header text intact when editing.
+# ---------------------------------------------------------------------------
+
+# Command prefix that runs tools inside the project environment. These
+# targets are opinionated on uv (the `uv sync` calls below assume it) and on
+# a src/ layout (docs-live watches src/); RUN stays a variable only so
+# one-off invocations can override it.
+RUN ?= uv run
+
+.PHONY: docs docs-strict docs-linkcheck docs-live test-docs docs-doctest clean-docs
+
+# Build HTML documentation.
+docs:
+	uv sync --group docs
+	$(RUN) sphinx-build -a -b html docs/source docs/build/html
+	@echo "Open docs/build/html/index.html"
+
+# Strict build: fail on any warning.
+# Use this in CI to catch broken cross-references, orphaned pages, and
+# autodoc surprises before they reach the main branch.
+docs-strict:
+	uv sync --group docs
+	$(RUN) sphinx-build -W --keep-going -a -b html docs/source docs/build/html
+
+# Check external links. Kept separate from docs-strict because it depends on
+# the network and is therefore flaky in CI and useless offline.
+docs-linkcheck:
+	uv sync --group docs
+	$(RUN) sphinx-build -a -b linkcheck docs/source docs/build/linkcheck
+
+# Live-reload mode: rebuild on file change. Watches both docs source and src.
+docs-live:
+	uv sync --group docs
+	$(RUN) sphinx-autobuild -a -b html docs/source docs/build/html \
+		--watch src \
+		--open-browser
+
+# Run the docs drift-tripwire test suite.
+test-docs:
+	$(RUN) pytest tests/docs
+
+# Run Sphinx doctest builder to verify code examples in docs.
+docs-doctest:
+	uv sync --group docs
+	$(RUN) sphinx-build -a -b doctest docs/source docs/build/doctest
+
+# Remove build artefacts and auto-generated API stubs. The _apidoc path must
+# match the ``:toctree:`` directory in docs/source/reference/python-api.md.
+clean-docs:
+	rm -rf docs/build docs/source/reference/_apidoc

template/README.md.jinja

@@ -37,6 +37,31 @@ make test
 make lint
 ```
 
+## Documentation
+
+Documentation is a [Sphinx](https://www.sphinx-doc.org/) + [MyST](https://myst-parser.readthedocs.io/)
+site. Only `docs/source/` is rendered; it is organised by audience (orientation /
+users / operators / maintainers) following the [Diátaxis](https://diataxis.fr/)
+model. Author meta-rules live under `docs/source/contributing/`
+(`documentation_guide.md`, `voice.md`, `writing_documentation.md`).
+
+```bash
+make docs          # build HTML into docs/build/html
+make docs-strict   # build with -W (warnings are errors) — use this in CI
+make docs-live     # live-reloading preview server
+make test-docs     # run the docs drift-tripwire tests in tests/docs/
+```
+
+`tests/docs/` pins documented facts (exported symbols, defaults, the toctree
+structure) to the source so that code/doc drift fails the build. Extend it as
+you document the project.
+
+The scaffolding is maintained with the
+[`update-docs` and `check-docs`](https://github.com/mariushelf/claude-swe-tools)
+skills: `check-docs` audits the docs against the code and emits a report;
+`update-docs` repairs the gaps. Run `check-docs` periodically (or in CI) and
+feed its report to `update-docs` to keep the docs current.
+
 ## Releasing
 
 Releases are managed via [python-semantic-release](https://python-semantic-release.readthedocs.io/).

template/docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline }}
+
+.. automodule:: {{ fullname }}
+{%- if modules %}
+   :no-members:
+{%- endif %}
+
+{% if not modules %}
+   {% block attributes %}
+   {%- if attributes %}
+   .. rubric:: {{ _('Module attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {% block functions %}
+   {%- if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {% block classes %}
+   {%- if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {% block exceptions %}
+   {%- if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+{% endif %}
+
+{% block modules %}
+{%- if modules %}
+.. rubric:: {{ _('Submodules') }}
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{%- endblock %}

template/docs/source/adr/README.md

@@ -0,0 +1,4 @@
+# Architecture decision records (folder index)
+
+The section index for this folder is in [index.md](index.md).
+This README exists only as a landing page when browsing the folder on GitHub — the canonical entry point is `index.md`.

template/docs/source/adr/index.md

@@ -0,0 +1,26 @@
+# Architecture Decision Records
+
+ADRs record significant architectural decisions: the context, the options
+considered, and the rationale for the choice made. They are not changed after
+the decision is accepted; superseded records are moved to `obsolete/`.
+
+ADR files are named `NNN-short-slug.md` (e.g. `001-choose-web-framework.md`).
+
+<!-- EDIT: Add ADR entries to the table below. -->
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| — | *(no ADRs yet)* | — |
+
+<!-- The ``obsolete/*`` glob keeps superseded ADRs reachable in the doctree
+so a strict (-W) build does not flag them as orphans. Sphinx warns when a
+glob matches zero documents, so ``obsolete/index.md`` must stay in place: it
+guarantees the glob always matches at least one page. -->
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+:glob:
+
+obsolete/*
+```

template/docs/source/adr/obsolete/index.md

@@ -0,0 +1,7 @@
+# Obsolete ADRs
+
+ADRs that have been superseded are moved here from `adr/`. They are kept for
+the historical record; the decisions they document no longer apply.
+
+Do not delete this page: the `obsolete/*` glob in the ADR index toctree must
+always match at least one document, or a strict (`-W`) Sphinx build fails.

template/docs/source/architecture/README.md

@@ -0,0 +1,4 @@
+# Architecture (folder index)
+
+The section index for this folder is in [index.md](index.md).
+This README exists only as a landing page when browsing the folder on GitHub — the canonical entry point is `index.md`.

template/docs/source/architecture/implementation/index.md

@@ -0,0 +1,11 @@
+# Implementation
+
+Detailed implementation notes: data flow, module responsibilities, and
+non-obvious design choices that are not obvious from the code alone.
+
+<!-- EDIT: Add implementation pages to this toctree as they are written. -->
+
+```{toctree}
+:maxdepth: 1
+
+```

template/docs/source/architecture/index.md

@@ -0,0 +1,23 @@
+# Architecture
+
+How the project is built — its structure, key components, and the reasoning
+behind major design decisions. This section is aimed at maintainers and
+contributors who need to understand the internals.
+
+```{toctree}
+:maxdepth: 2
+
+implementation/index
+```
+
+## Overview
+
+<!-- EDIT: Replace the placeholder diagram below with one that reflects the
+actual system. Add prose describing the components and their interactions. -->
+
+```{mermaid}
+graph TD
+    A[Entry point] --> B[Core]
+    B --> C[Adapter A]
+    B --> D[Adapter B]
+```

template/docs/source/concepts/README.md

@@ -0,0 +1,4 @@
+# Concepts (folder index)
+
+The section index for this folder is in [index.md](index.md).
+This README exists only as a landing page when browsing the folder on GitHub — the canonical entry point is `index.md`.

template/docs/source/concepts/index.md

@@ -0,0 +1,12 @@
+# Concepts
+
+Explanation pages — the "what" and "why" of the project. Each page covers one
+concept in depth: its purpose, its place in the overall design, and the
+trade-offs behind it.
+
+<!-- EDIT: Add concept pages to this toctree as they are written. -->
+
+```{toctree}
+:maxdepth: 1
+
+```