Creating High Quality Documentation with Sphinx

Why Smarter. This documentation is itself a large Sphinx project, with more than a thousand pages, that combines hand-written guides, architecture decision records, and API references generated from Python docstrings by autodoc, and is published to Read the Docs at every release. Students can contribute to it on their first day.

Look at. docs/source/, its conf.py, and the reStructuredText docstrings in any Python module.

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

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.

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.

• Classroom bootcamp: 8 hours
• Two-week online course: 6 hours
• Four-week online course: 12 hours

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