[Python-Dev] The docs, reloaded

[Georg Brandl]

Hi,

over the last few weeks I've hacked on a new approach to Python's documentation.
As Python already has an excellent documentation framework, the docutils, with a
readable yet extendable markup format, reST, I thought that it should be
possible to use those instead of the current LaTeX->latex2html toolchain.

For the impatient: the result can be seen at <http://pydoc.gbrandl.de>.

I've written a converter tool that handles most of the LaTeX markup and turns it
into reST, as well as a builder tool that adds many custom directives and roles,
and also features like index generation and cross-document linking.

(What you can see at the URL is a completely statical version of the docs, as it
would be shipped with the distribution. For the real online docs, I have more
plans; I'll come to that later.)

So why the effort?

Here's a partial list of things that have already been improved:

- the source is much more readable (for examples, try the "view source" links in
   the left navbar)
- all function/class/module names are properly cross-referenced
- the HTML pages are generated from templates, using a language similar to
   Django's template language
- Python and C code snippets are syntax highlighted
- for the offline version, there's a JavaScript enabled search function
- the index is generated over all the documentation, making it easier to find
   stuff you need
- the toolchain is pure Python, therefore can easily be shipped

What more?

If there is support for this approach, I have plans for things that can be added
to the online version:

- a "quick-dispatch" function: e.g., docs.python.org/q?os.path.split would
   redirect you to the matching location.
- "interactive patching": provide an "propose edit" link, leading to a Wiki-like
   page where you can edit the source. From the result, a diff is generated,
   which can be accepted, edited or rejected by the development team. This is
   even more straightforward than plain old comments.
- the same infrastructure could be used for developers, with automatic checkin
   into subversion.
- of course, plain old comments can be useful too.

Concluding, a small caveat: The conversion/build tools are, of course, not
complete yet. There are a number of XXX comments in the text, most of them
indicate that the converter could not handle a situation -- that would have
to be corrected once after conversion is done.

Waiting for comments!

Cheers,
Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.