[Python-Dev] The docs, reloaded

[Talin]

Georg Brandl wrote:
> 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.

Very impressive.

I should say that although in the past I have argued strongly against 
the use of reST as a markup language for source-code comments (because 
the reST language only indicates presentation, not semantics), I am 100% 
supportive of the use of reST in reference documents such as these, 
especially considering that LaTeX is also a presentational markup (at 
least, that's the way it tends to be used.)

I know that for myself, LaTeX has been a barrier to contributing to the 
Python documentation, and reST would be much less of a barrier. In fact, 
I have considered in the past asking whether or not the Python 
documentation could be migrated to a format with wider fluency, but I 
never actually posted on this issue because I was afraid that the answer 
would be that it's too hard / too late to do anything about it. I am 
glad to have been proven wrong.

-- Talin