Introducing py-rest-doc
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:
If I wanted to boast, I would probably mention that
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 :)
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.)
- 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".
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
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 :)
I am floored. This is fantastic! kudos for getting this far! I don't think you can boast enough, so boast away.
— Doug Napoleone on Monday, June 25, 2007 0:03 #
I like that the modules index doesn't list all of the distutils.* or xml.* modules by default. It'd be cool if it didn't list the platform-specific ones by default as well - with perhaps a checkbox to enable listing them?
— Richard Jones on Wednesday, July 18, 2007 1:06 #
— richmoore on Wednesday, July 18, 2007 8:59 #
@richmoore: There is already much more content per HTML page compared to the old docs. But certainly it should be possible to add a builder that concat whole subtrees in one page.
— Georg on Wednesday, July 18, 2007 23:10 #
What needs to be done to get it finished and deployed on docs.python.org?
Will there be a locally-installable version so I can browse the documentation while offline?
— Marius Gedminas on Thursday, July 19, 2007 13:13 #
— illume on Friday, July 20, 2007 7:20 #
WRT the locally installable version: at the moment, a plain HTML version or an HTML Help version can be built too, and I'll work with Ron Adam, who rewrites pydoc, on integration.
— Georg on Friday, July 20, 2007 15:56 #
Personally I don't prefer the color scheme (the sidebar is too dark)--would prefer something more along the lines of www.python.org.
The navigation is good except for one small flaw: it needs next/previous/modules/index links at the bottom of the page (like those at the top of the page). Breadcrumbs would be a nice bonus down there too. When I was reading some sections (i.e. the tutorial introduction) I would get to the bottom of the page and then wonder "what now?"
Anyway, this is meant to be constructive criticism. Excellent effort.
— Daniel on Tuesday, July 24, 2007 1:07 #
Putting navigation elements at the bottom is a very good suggestion!
— Georg on Tuesday, July 24, 2007 11:32 #
— Ali on Wednesday, July 25, 2007 23:11 #
Ahem. Looks like you're modest enough to avoid mentioning prior projects with similar feature-sets as well...
— FF on Saturday, July 28, 2007 19:29 #
In fact, I have you, as well as a few others who did previous work in this direction, in the draft of "About these documents" that's lying around here.
— Georg on Sunday, July 29, 2007 8:44 #