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!