[Doc-SIG] two subjects: docutils for python docs, and integrating documentation in source code

[Michael Foord]

Martin Blais wrote:

>hi
>
>after some fiddling this morning, i'm getting all worked up over some
>things i feel are missing w.r.t. the python documentation.
>
>1. writing python documentation using docutils, is it possible?
>
>here's a cool idea, i don't know if it's been discussed here before,
>but do you think it would be possible to add docutils directives for
>all the markup that the python documentation requires?  ( in particular, 
>there could be directives to automatically extract much of the 
>information from the python declaratoins themselves, using 
>inspection ) e.g.
>
>.. funcdesc:: foo( param1, param2=True )
>
>would automatically parse the function declaration and generate
>appropriate output.  a sort of specialized rest input (just some
>directives really) with specialise latex output.   we could even
>output using the current LaTeX
>macros that the python docs are currently using...  
>
>  
>
[snip..]

A brief but resounding +1 to the idea of standardising Python doc 
generation using docutils.

The python documentation is very nicely presented and *ought* to be the 
standard style for people documenting third party modules. The toolset 
to produce the documentation currently seems a bit arcane. I may just be 
a luddite - but every time I've looked into it I've ended up with a 
headache (although I've not put any degree of real effort into it !).

Being able to write docs in reST and use docutils to produce them sounds 
great. The *main* drawback will be that docutils doesn't yet support 
multipage documents.

Best Regards,

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