[Python-Dev] The docs, reloaded
talin at acm.org
Sun May 20 03:29:48 CEST 2007
Georg Brandl wrote:
> 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.
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.
More information about the Python-Dev