Projects can succeed or fail because of their documentation. When you write, you need to concentrate on your prose—not on how to get text rendered, indexed, highlighted, and cross-referenced. The Sphinx documentation framework exists to make these parts easy so you can focus on writing. This tutorial will use hands-on exercises to teach you to write, theme, and deploy documentation using Sphinx!
This tutorial has been presented at PyCon in three previous years. It alternates brief “lightning lectures” with carefully designed hands-on exercises that introduce Sphinx and that take students through each of its features. The pace should give students a good foundation, while still allowing a few minutes in each unit to experiment.
The material has been improving each year and in 2013, for the first time, it will include a unit on how to theme and deploy documentation — first to readthedocs.com, and then to Heroku!
The first half of the tutorial will help students install Sphinx, quick-start a new project, and then write and style basic documentation for a tiny sample Python library. The sessions will build in complexity, starting with basic formatting, and then progressing through document organization, code and topic cross-referencing, indexing, and finally a look at how to support an audience that ranges from beginner to expert. Tips will be provided for making Sphinx docs friendly to version control, and about how and when to use Sphinx "autodoc" to pull API documentation directly from your code.
The second half of the tutorial will step back and look at how your Sphinx docs relate to your entire project: how example code in documentation can serve as runnable tests, how snippets of example input and output can be pulled into Sphinx, and how your projects can benefit from automation that runs tests and deploys documentation automatically. Finally, we will see how to use Sphinx to produce several alternative documentation formats, how to customize or completely replace the HTML that it produces, and, finally, how to deploy documentation to as service like readthedocs.com or Heroku.
The Sphinx approach will be compared 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.