[Doc-SIG] Python docs in reST
mike at pcblokes.com
Thu May 26 10:05:32 CEST 2005
Felix Wiemann wrote:
>Martin Blais wrote:
>>1. why exactly do we want to change the documentation system?
>* We want to have **well-readable** documentation source.
>* We want to get **flexibility** in that we can modify the parsed
> document using Python code.
> In particular I have Docutils' document tree in mind -- use
> rst2pseudoxml.py to see what it looks like. You can easily apply
> transformations on these trees, using your favorite programming
> language ;-). This is not (easily?) possible with LaTeX.
>* We want an **easy-to-use** documentation system. Any documentation
> should be renderable by typing "sometool.py input.txt output.html".
> Getting multi-document output should be similarly easy.
As a side issue - it would be nice for developers of other
modules/projects to be able to *easily* generate documentation that is
consistent with the (IMO) nice looking Python documentation.
I confess to *not* having looked into Latex markup [#]_ - so I haven't
a clue how difficult it is to use, but I love reST. If Latex is *that*
easy to use why bother creating reST ;-)
In order to achieve this (becoming a useful documentation system for
Python projects) - docutils needs to be capable of handling anything
that is in the Python docs. So it is certainly in the interests of the
docutils project to address these issues... whether that means it should
be adopted as *the* method of documenting Python is another matter.
Hopefully natural selection will start to work...
Surely implementing a Python source reader (that works by introspection
or whatever) that extracts docstrings and inserts it *into* a reST
document (still a two pass process) would help as a short term measure.
Hmmm..... I might even implement something like that myself.
.. [#] I use HTML and reST... I honestly can't be bothered with another
More information about the Doc-SIG