Okay. I’ll admit it. At first, I was not that into Sphinx. It was developed a while back to provide a nice, easy, attractive framework for writing Python documents. (I blogged about the results of this effort a while ago.)
So the deal is, it’s for hand-writing documentation. This sets it apart from epydoc, which generates API documentation, including object inheritance diagrams and so on and so forth. Sphinx has a much more restricted set of goals — generate documentation, and include lots of cool markup methods for documenting modules and whatnot, but require that most of it is hand-written.
Over the last couple weeks, I’ve been doing a big push toward cleaning up, stabilizing and release my toolkit. And I’ve decided that the main documentation is going to be provided through Sphinx. Frankly, it’s gorgeous, even with the default template. And it’s a dream to work with.
But what really got me going — and what inspired this post — was the inclusion of auto-documenting utilities. It’s not nearly as aggressive as epydoc, because you have to specify the particular modules/classes/methods that you want it to introspect, but it will parse docstrings and generate documentation from this, allowing that documentation full access to the Sphinx ReST directives.
This is awesome. I’ve written an outline of the documentation that I want to include with the 0.3 release, but I’ve got a ways to go before that documentation is all written.
This, combined with the rather dee-eye-ess-kay looking data I got last week (before the supercomputer I do my work on had a series of briefly disabling hiccups) has put me in a pretty good mood.
Tags:
documentation,
python,
Science,
sphinx,
yt