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 <fill in the blank> 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 …
In places normally filled with glowing Apple logos and Windows laptops, Linux users are becoming more...
IBM says cybercriminals are starting to grab unstructured data, spam has rebloomed 400% and ransomware...
A review of 18 companies that offer free cloud storage
The Russian government used "thousands" of internet trolls and bots to spread fake news, in addition to...
Everyday we create the problem of IT storage creep. If we produce the problem, though, we can solve it....
If you are online today, checking email, buying someone a gift, posting to Facebook, paying bills,...
Good-bye, programming peers; hello, power to abuse at your whim