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
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.