Sessions at PyCon US 2012 about Python and Documentation in H2

Thursday 8th March 2012

• Documenting Your Project With Sphinx

  by Brandon Rhodes

  Python projects can succeed or fail because of their documentation. Thanks to Sphinx, Python now has a “documentation framework” with indexing, syntax highlighting, and integration with your code. Students will be given a small undocumented Python package, and during the exercises they will give the package a tutorial and reference manual. Plus: deployment and theming!

  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:

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

  • Documentation
  • Python
  • Sphinx Docs

  At 9:00am to 12:20pm, Thursday 8th March

  In H2, Santa Clara Convention Center

  Coverage video