Python Module of the Week, meet reST and Sphinx
Release 1.65 of the Python Module of the Week includes HTML documentation created with Sphinx from reStructuredText versions of all of the posts so far. The documentation is included in the source download, or you can browse it online from the PyMOTW home page.
I have been a long time StructuredText user, using it with Zope and some home-grown tools to produce DocBook output for dead-tree documentation. When reST was being created, I dismissed it as comparatively ugly and overly complicated. The quality of the toolset surrounding it now makes it a very attractive alternative for generating documentation, especially if you need to produce different versions or multiple output formats. After seeing the power and features it has that regular ST doesn’t, I’m a convert.
A big “Thank you!” goes out to John Benediktsson for doing the original HTML-to-reST conversion. It would have taken me ages to do it myself, so if it was left up to me alone it probably never would have been done.
The new versions of the docs online on the PyMOTW home page are in a form that should be easier to browse than my blog archives. There is still some work to be done to make the content consistent, mostly due to my writing style and approach evolving over time. I’ll be tackling those updates bit by bit, and converting the 2-3 modules that haven’t been converted at all yet. I am releasing what I have now because I wanted to finish the major portion of the migration this weekend.
The Sphinx development team also deserves a big “Thank you!” from me. I’ve been using Sphinx at my day job to produce some documentation, and found that I liked it enough that it was the obvious choice for the PyMOTW site conversion. Incredibly, the Django base template I use for the rest of my site worked the first time the Jinja template engine used by Sphinx. I had to clean up some styles, but the template didn’t bomb out and produced good HTML the first time.