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 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.
7th–15th March 2012