2010/Sphinx - the ultimate tool for documenting your software project
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 notesEver 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.
Here, Nate showed an example documentation project, which was based on kind advice he gave me for one of my open source projects.
Sphinx uses Pygments for syntax highlighting.