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 _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
