Python projects can succeed or fail based on their documentation. Thanks to Sphinx, Python now has a "documentation framework" that provides convenient indexing and automatic syntax highlighting, and can also integrate your documentation with your code (your documentation can be run as a test, and your class and function docstrings can become your reference documentation). Students will be given an undocumented sample Python package, and be lead through exercises that result, by the end of the tutorial, in their giving the package a full tutorial and reference manual. Deployment and theming will also be taught.

Besides a 15-minute introduction and 15 minutes for questions and discussion at the end, the tutorial will be organized in six 25-minute sessions which each involve a short lecture and then an interactive exercise that asks the students to apply what they have just learned. Here are the major topics covered by each of the six sessions:

1. The reStructuredText markup language and its syntax; the standard doctools; and the two different conventions that Sphinx can support for laying projects out as directories and files.
2. The Sphinx documentation build process on both Unix and Windows; how to arrange your project documentation in a way that will make sense to novice, experienced, and expert users alike; and how Sphinx supports connections between different pages of documentation.
3. Running code examples in the documentation as doctests; the pros and cons of pulling docstrings from the code as API documentation (and how to do it if it proves necessary); and including non-doctest full code listings in the documentation.
4. Referencing headings in the same document; cross-referencing between documents; making class and method names automatically link to their entry in the API documentation; and how to make code objects appear in the index.
5. Theming with custom HTML and CSS, for students who happen to know web design; plugging in pre-made Sphinx themes; and how to integrate Sphinx into an entire web site for their product.
6. Shipping documentation with your package on PyPI; installing it readthedocs.org; making sure that documentation gets included with a binary install; using a version control source browser to view documentation directly in their project trunk; and deploying Sphinx to a web site.

The Sphinx approach will be linked to other successful documentation systems in our computing heritage, most notably in the practices it shares in common with the Unix Documenter's Workbench (DWB) of the 1970s.