2010/Sphinx - the ultimate tool for documenting your software project

From Open Source Bridge Wiki
Jump to: navigation, search

Open source software projects can succeed or fail based on their documentation. Thanks to Sphinx, open source developers now have a “documentation framework” that provides convenient indexing and automatic syntax highlighting, integrates your documentation with your code, and can automatically generate a beautiful manual as a PDF document.

Speaker: Nate Aune

Return to this session's details

Contributed notes

Ever had to maintain software someone else wrote? Maybe "someone else" was you, several years ago. RTFM, you say? Sure, but you need a better FM.

Why document? Explaining your project helps you find problems. In short, documentation makes your software better.

Write docs before code. Plenty of examples. Make it part of the process. Make it easy for contributors.

So, why use Sphinx? Lots of projects use it, including Python and Bazaar. There's even a non-techie "Wine Cellar Book" written in Sphinx! All just text; no obtuse binary formats.

Sphinx auto-generates multiple formats (including TeX and PDF), working JavaScript search field, cross-references, indices, syntax-highlighted code. Source format is reStructuredText.

Here, Nate showed an example documentation project, which was based on kind advice he gave me for one of my open source projects.

Next up was an example of a book about the Repoze software, which was done with Sphinx.

Sphinx uses Pygments for syntax highlighting.