Documentation and things…
Documentation: how we love to read it and how we grumble when it’s not there; but how we hate to write it. Well, not exactly hate; more, can’t get round to start writing it. Those who follow the in-development version of the Python docs will have noticed a number of significant differences, along with a lot of familiar stuff: Same Quality, Great New Taste! A team spearheaded by (and pretty much consisting of) Georg Brandl has undertaken a massive transformation of the Python docs, leaving everything exactly the same, only better.
The new docs are in rst format with special markup added to suit the specifics of the Python documentation. The Sphinx documentation toolset (not to be confused with the Sphinx search engine) written and maintained by Mr Brandl then takes the rst files and renders them as HTML, CHM (the Windows Help File format) or as a web app using werkzeug behind WSGI.
The effect of all this, combined with Python’s move to the Roundup tracker is that the docs are now rather more accessible to the average punter, who can then provide a patch much more easily. In addition, Georg continues to develop Sphinx and to nurture the docs, just as Fred Drake has done for all the years in which they have been in the original LaTeX form.
I’ve always felt that, even though not all of us are able to contribute code patches, pretty much everyone’s able to help with the docs, whether picking up errors or inconsistencies, filling gaps, suggesting new approaches or whatever. My plea is: look through the docs, pick up even tiny typos and report them as bugs, ideally giving a patch against the current Subversion trunk. Georg’s very responsive to issues and is always grateful for patches. In addition, there’s a docs mailing list if there’s some rather wider issue which merits discussion. Join in!
Christopher Arndt said,
Wrote on March 16, 2008 @ 12:52 am
The docs produced by sphinx just look great! I think I am going to steal it for documenting my own projects! ;-)
tim said,
Wrote on March 16, 2008 @ 7:47 am
@Christopher: exactly what I plan to do, myself. I know that Georg has put some work in lately separating out Sphinx-the-toolkit from Sphinx-the-Python-doc-machine. I haven’t yet had time to figure out what I need to put where for my own docs. If you get there first, please do post.
Christopher Arndt said,
Wrote on March 16, 2008 @ 11:14 am
It’s very easy:
- Checkout python-doctools from svn
- Install Pygments
- Copy “conf.py” into the directory where you keep your
rest doc sources and adapt it
- Write an “index.rst” with “.. toctree::” directives
listing the source files in the order you want to
have your sections.
- Create the output directory
- Run “shinx-build.py [-E] srcdir outdir”.
Look at “documenting/markup.rst” in a checkout of the Python documentation > 2.5. for documentation of the rest directives you can use.
tim said,
Wrote on March 16, 2008 @ 12:07 pm
Excellent. Thanks very much.
Georg said,
Wrote on March 16, 2008 @ 12:29 pm
Hey Tim,
many thanks for the encouraging article! You’re right, I’ve worked a lot on making Sphinx a standalone package, and I’m almost done. The most pressing need, viz. docs, has been addressed (look at the preview at http://sphinx.pocoo.org), and I shall be preparing a PyPI package soon.