by Nate Aune
Sphinx makes documenting your project almost too easy.
You can even integrate your documentation with your code in that your documentation can be run as a test, and your class and function docstrings can become your reference documentation.
Markup as well-designed as reStructuredText is not only a lot of fun to use, but it also very cleanly separates content from design. Authors working in plain text tend to produce clean, readable content without the messy markup often associated with visual HTML editors, or, worse yet, the disaster that is Microsoft Word.
Sphinx is written in Python, but you can use it to document anything. It has a built-in search engine, generates table of contents and indexes, and because the files are just text files, you can check them into your favorite version control system and easily collaborate with and merge changes from other documentation contributors.
We will look at several popular open source software projects that are already using Sphinx, and show you how you can get started using Sphinx to document your software project.
1st–4th June 2010