[Doc-SIG] Python docs in reST

Michael Foord 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?
>>    
>>
>
>Ideas:
>
>* 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.

Best Regards,


Fuzzy
http://www.voidspace.org.uk/python

.. [#] I use HTML and reST... I honestly can't be bothered with another 
one... sorry...


More information about the Doc-SIG mailing list