If you read the python-dev mailing list, you have probably already known that for the last few months I worked on a new framework for the documentation of Python.
The current toolchain uses LaTeX input files, combined with a few custom Python scripts. These are processed either by latex itself to produce the printable version ready to download at docs.python.org
, or by a heavily customized latex2html (yes, in Perl) to produce the static HTML pages on that server. Users who want to contribute to the docs are referred to the SourceForge issue tracker.
This has worked well so far, but it has two downsides:
- The generated HTML is static and it is hard to customize the output as well as add nice user participation features.
- The imaginary barrier for potential contributors is high.
(I say "imaginary" because LaTeX markup really isn't that hard after all, and devs have offered to mark up text-only contributions. Still, experience shows that users perceive it as complicated to contribute to the docs.)
This is why the new framework does two things:
- It uses the widely-known (in the Python community) reStructuredText as its markup language.
- It can create both static HTML pages for distribution, and a web application for serving at docs.python.org, with participation features like commenting and "suggest-a-patch".
Of course, these are not the only "new" features that the new framework has, but they are the most convincing ones.
If I wanted to boast, I would probably mention that
- all function/class/module names are properly cross-referenced
- you have a quick dispatcher, mock-URL: http://docs.python.org/urllib.urlopen
- Python and C code snippets are syntax highlighted
- there's a builtin 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
- the HTML pages are generated from proper templates, using a language similar to Django's template language
But as I'm modest, I won't mention it. :D
Of course, the whole thing is a long way from finished, but you can see a preview here
. (The interactive features might not work as expected, also this is just a tiny server, so bear with its slowness.) If you have comments or questions, just drop me a line: georg at python org!
In case you wonder, the app is WSGI-based and served by a simple wsgiref server.
Also, I have to give credits to Armin for most of the design and for much of the web app code.
By the way, the thing that kept many people from even trying to change the Python docs' source format was how to parse and convert the LaTeX. That I managed to do it should be proof that it isn't that hard at all :)