Creating High Quality Documentation with Sphinx

Why Smarter. Documentation is usually taught on a toy project with three pages, so students never face the real problems: keeping hundreds of pages consistent, generating reference from code without it going stale, checking links quickly, and writing for readers who arrive from a search engine. This documentation, published at docs.smarter.sh from docs/source/, is itself a large Sphinx project that has all of them:

  • More than nine hundred pages. Hand-written guides for every resource, the platform and the framework, which follow one pattern (see the Guardrail page), thirty-one Architecture Decision Records, these instructor course plans, and more than five hundred pages of API reference.

  • Reference generated from the code. Autodoc publishes reStructuredText docstrings, with sphinxcontrib_django for Django models, autodoc_pydantic for Pydantic models and sphinx_autodoc_typehints for type hints, all configured in conf.py.

  • Examples that are real files. Manifests are kept in example-manifests/ and included with literalinclude, so an example in the docs is the same file that a reader can apply.

  • A pipeline that keeps up. Read the Docs builds every release from .readthedocs.yml, the pydocstringformatter and codespell hooks check every commit, and a script checks every link and autodoc target in seconds, because the full build takes twenty minutes.

  • Written rules. Evergreen prose with no “what’s new” sections, terms defined on first use, valid manifests in every example, and docs updated in the same change as the code, as the smarter-sphinx-docs and smarter-docstrings skills set out.

  • A new kind of reader. The documentation is written as much for coding agents as for people, and CLAUDE.md and the Agent Skills are documentation whose only reader is an agent.

Students can contribute to it on their first day, and see their page published.

What the course covers. Documentation as a product, and who reads it; docs as code: plain text, version control, review and CI; reStructuredText: markup, directives, roles, tables and includes; Sphinx: conf.py, extensions, toctrees, themes and the build; the four kinds of documentation in Diátaxis; writing clearly, with examples that work and evergreen prose; testing documentation on readers; docstrings, autodoc and generated reference for Django and Pydantic models; Architecture Decision Records; publishing on Read the Docs; maintenance, link checking and ownership; and writing for coding agents.

Look at.

Each course plan lists every file that it uses under Smarter in the Source Code.

Read. Documentation Style Guide & Technical Reference, ADR 029 on docstrings, ADR.

Exercises.

  • Find a page that is unclear or out of date, and improve it in a pull request.

  • Write an Architecture Decision Record for a decision of their own, following the existing ones.

  • Write the docstrings for a module, and see how autodoc renders them.

  • Run check-docs.sh on a page, break one of its links on purpose, and see the check catch it.

Course plans. Three complete, ready-to-teach plans, each with a schedule, graded assignments and rubrics, two capstone projects, recommended texts, further study and technical prerequisites. See Course Formats and Grading for what the formats have in common.

See the Smarter Instructor Guide to install Smarter and set up a class.