Sphinx: An outstanding open source documentation platform

If you’ve ever dealt with software or engineering development of any kind development you’ll know that one of the hardest things to produce is good documentation. And I’m not talking “great” documentation, I’m talking about simply serviceable documentation that covers the nuts and bolts of what the product is supposed to do.

The reason why this goal is hard to achieve is that writing documentation is boring. It’s not like coding which is totally engrossing. On the other hand, documentation is, well, tedious at best, and soul-destroying at worst. Why? Because most tools for writing documentation aren’t very good. They’re slow to use, they’re too complex, they don’t make it easy to cross-reference, they’re hard to adapt to group use … in other words, they’re mostly not designed nor a good fit for development documentation. 

Now, what if I told you there was a documentation tool that was easy, effective, and took the pain out of documenting your code? Here’s what a user is reputed to have said about such a tool called Sphinx:

“Cheers for a great tool that actually makes programmers want to write documentation!”

That is like saying you’ve discovered something that makes people want to pay their taxes or volunteer to have a root canal.

Sphinx is a free, open source project written in Python and, not surprisingly, is really well suited for documenting Python projects. Now, before you harrumph “Meh, I code in which isn’t at all like Python!” be aware that Sphinx supports several other languages (C and C++ support is in development).

So, what can Sphinx do? Here’s Sphinx’ top features:

Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text

Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information

Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children

Automatic indices: general index as well as a language-specific module indices

Code handling: automatic highlighting using the Pygments highlighter

Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more

In fact, the last item, extensions, is one of the most compelling parts of Sphinx and include modules for adding Google maps and charts, integrating Google Analytics, creating images with gnuplot, embedding YouTube videos and Slideshare presentations, and support for Ruby, Erlang, PHP, Coffeescript … it’s a long list of enhancements.  

Sphinx is an elegant and effective documentation solution and can be deployed on a public server for end user or community documentation or on an internal server for group use. To run Sphinx you’ll need  Python 2.5 or Python 3.1 as well as the docutils and Jinja2 libraries on your server.

Have your programmers and engineers embraced documentation? Will Sphinx do the impossible and get them to actually enjoy documentation? If you try, or have tried, Sphinx, let me know what you think …