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 …
Networking and collaboration vendor Avaya declared bankruptcy on Thursday, calling the move part of its...
The Air Force Research Lab (AFRL) tapped into that notion today as it awarded a $750,000 grant to...
The U.S. government reportedly pays Geek Squad technicians to dig through your PC for files to give to...
The AR in Action conference redefines augmented reality to include many diverse technologies.
A potential victim tries to turn the tables on a spear phisher.
Expectations are high and steadily growing for how serverless computing can revolutionize the way...
Tech companies keep upping the ante to attract new talent and keep current employees happy, and in the...