Documentation with Sphinx: Two-Week Online Course

A two-week online course on writing high quality technical documentation with Sphinx and reStructuredText, taught on Smarter’s own documentation. Smarter’s documentation, published at docs.smarter.sh from docs/source/, has more than nine hundred pages: user guides that follow one pattern, thirty-one Architecture Decision Records, and more than five hundred pages of API reference generated by autodoc from reStructuredText docstrings, including Django and Pydantic models. Its conf.py, Read the Docs configuration and fast checks are all in the repository, and it is written for coding agents as much as for people. There are six 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers Sphinx, reStructuredText and writing, and week 2 covers docstrings, ADRs and publishing. See Course Formats and Grading for the format, the grading scale and the course policies, and Creating High Quality Documentation with Sphinx for an overview of the subject.

At a Glance

Students

Developers, technical writers, and students in technical communication.

Deployment

Each student has a fork and clone of the repository with the virtual environment set up, and a small Sphinx project of their own for building quickly. The full Smarter docs build takes about 20 minutes; students may run it once, overnight.

Workload

3 hours of instruction and 4 to 6 hours of assignments each week.

Cost

Free.

Learning Objectives

By the end of the course, students can:

  1. Write correct reStructuredText, and organize a Sphinx project.

  2. Classify documentation by purpose, and write each kind well.

  3. Write clear, accurate, evergreen technical prose.

  4. Write docstrings that autodoc renders as API reference.

  5. Write ADRs, and publish documentation on Read the Docs.

Technical Prerequisites

  • Required: the command line and a text editor.

  • Required: Git and GitHub, including pull requests.

  • Required: Python 3, and virtual environments.

  • Helpful: reading Python, and Markdown.

Schedule

The files that the lectures refer to are listed in full under Smarter in the Source Code.

Week

Item

Content

1

Lecture 1 (30 min)

Documentation as a product. Readers, docs as code, Diátaxis, and a tour of docs/source/.

1

Lecture 2 (30 min)

Sphinx and reStructuredText. conf.py, extensions, toctrees, markup, cross-references, tables and includes.

1

Lecture 3 (30 min)

Writing clearly. Audience, plain language, examples that work, and evergreen prose. Documentation Style Guide & Technical Reference.

1

Live session 1 (90 min)

Live edit of a Smarter page, then pairs critique two pages against Diátaxis. Start Assignment 1.

2

Lecture 4 (30 min)

Docstrings and autodoc. Field lists, cross-references to Python objects, and ADR 029.

2

Lecture 5 (30 min)

Architecture Decision Records. Nygard’s format and Smarter’s ADRs.

2

Lecture 6 (30 min)

Publishing and maintenance. Read the Docs, link checking, docs in review, and keeping docs consistent with code.

2

Live session 2 (90 min)

Capstone presentations (about 5 minutes each, with 2 minutes of questions).

Assignment 1 is due at the end of week 1, Assignment 2 in the middle of week 2, and Assignment 3 and the capstone at the start of Live session 2.

Smarter in the Source Code

Every lecture, lab and assignment in this course rests on the files below. Every reference is to the main branch of github.com/smarter-sh/smarter, so that students can open each one during class, beside the published pages at docs.smarter.sh.

The Project

Topic

What Smarter does

Where to look

The source

More than nine hundred reStructuredText pages: user guides for each resource, the platform and the framework, thirty-one decision records, and more than five hundred pages of generated API reference.

docs/source/, docs/source/index.rst

The configuration

Sphinx with autodoc, napoleon, sphinx_autodoc_typehints, sphinxcontrib_django for Django models, autodoc_pydantic for Pydantic models, sphinx_design, sphinx_copybutton, intersphinx, a sitemap and the Read the Docs theme, with Django set up so that autodoc can import every module.

docs/source/conf.py

Publishing

Read the Docs builds and publishes the site, with its dependencies pinned in their own requirements file.

.readthedocs.yml, smarter/requirements/docs.txt

Building locally

make sphinx-docs builds the whole site, in about twenty minutes, which is why there is a faster check.

Makefile (sphinx-docs), docs/Makefile

Pages to Study

Kind of page

Example

Where to look

A resource guide

The Guardrail page: overview, how it works, a complete manifest, topic sections and a technical reference toctree, the pattern that every resource page follows.

smarter-resources/smarter-guardrail.rst

An autodoc page

A few lines that publish a module’s docstrings.

smarter-resources/guardrail/

Examples that are files

Manifests kept as files and included with literalinclude, so that an example in the docs is the same file that can be applied.

docs/source/example-manifests/

Decision records

Thirty-one ADRs and an introduction, each with status, context, decision, alternatives and consequences.

docs/source/adr/

A course plan

These instructor pages use list-tables, includes and cross-references heavily, and the .. include:: of this very table.

docs/source/smarter-instructors/

Docstrings and Checks

Topic

What Smarter does

Where to look

Docstrings worth copying

Module docstrings that explain why, not only what, such as the protections and their known limits in the hardened HTTP client, and the usage examples in the infrastructure facade. ADR 029.

plugin/plugin/safe_http.py, infrastructure/services/__init__.py

The docstring style

reStructuredText field lists (:param:, :returns:, :raises:), cross-references to Python objects, and the layout that the pydocstringformatter hook enforces.

smarter-docstrings/SKILL.md, .pre-commit-config.yaml

Fast checks

A script that checks every :doc: link and toctree entry, and imports every autodoc target, in seconds, and a linter that finds autodoc targets that fail to import.

check-docs.sh, docs/source/lint.py

Spelling

codespell on every commit, with the project’s own list of accepted words.

codespell.txt

Writing 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.

smarter-sphinx-docs/SKILL.md

Writing for agents

CLAUDE.md and sixteen Agent Skills: documentation whose reader is a coding agent.

CLAUDE.md, skills/

Graded Assignments

Assignment 1: An Improved Page

Students improve one page of Smarter’s documentation (an error, a missing example, a confusing passage), verified against the code.

Turn in: a pull request against their fork.

Criterion

Pts

Exemplary

Developing

Real improvement

7

Substantive.

Cosmetic.

Accuracy

5

Examples tested.

Untested.

Markup

4

Valid; targets exist.

Broken.

Pull request

4

Problem and fix explained.

No description.

Assignment 2: Docstrings for a Module

Students write the docstrings for a small module in Smarter’s style, and render them with autodoc in a small Sphinx project.

Turn in: a pull request against their fork, and a screenshot.

Criterion

Pts

Exemplary

Developing

Completeness

6

Every public object.

Gaps.

Usefulness

6

Why and when, not only what.

Restates names.

Style

4

Follows ADR 029; hooks pass.

Inconsistent.

Rendering

4

No warnings.

Broken.

Assignment 3: An ADR

Students write an ADR for a real decision, either in a project of their own or one already made in Smarter that has no ADR (for example a choice of library visible in the code).

Turn in: the ADR in reStructuredText, in the format of ADR.

Criterion

Pts

Exemplary

Developing

Context

5

The forces and constraints are clear.

Missing context.

Decision

4

Stated plainly.

Buried.

Alternatives

6

Two or more, fairly compared.

None.

Consequences

5

Good and bad consequences.

Benefits only.

Capstone Projects

Students choose one, and present it in Live session 2.

Capstone A: A Tutorial for Smarter

Learning objective. Write a tutorial that takes a newcomer to a working result, and test it on a real reader.

Students write a new tutorial for Smarter’s docs, with verified manifests, test it on a newcomer, and revise it.

What students turn in:

  • A pull request against their fork, linked into a toctree.

  • User test notes and changes made.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Tutorial form

20

One path, visible results.

Reference with steps.

Accuracy

25

Everything works as written.

Steps fail.

User test

20

Real reader; fixes made.

None.

Writing

20

Clear and concise.

Wordy.

Integration and presentation

15

Linked, valid; clear presentation.

Orphaned.

Capstone B: Documentation for Your Own Project

Learning objective. Build and publish a complete documentation site covering all four kinds of documentation.

Students set up Sphinx for a project of their own, with a tutorial, a how-to, an explanation, an API reference from docstrings and an ADR, published on Read the Docs.

What students turn in:

  • A repository and a link to the published site.

  • A Diátaxis mapping of the pages.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Four kinds of docs

25

Each serves one purpose.

Mixed.

API reference

20

Complete docstrings.

Sparse.

ADR

15

Real decision with alternatives.

Description only.

Published

20

Builds cleanly.

Not published.

Writing and presentation

20

Clear.

Inconsistent.

Further Study