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

[Martin Blais]

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...  which brings me to
the second issue


2. unifying source code and readable documentation

have fiddle with the python documentatoin sources recently, i find it
really hard to accept that the docs are separate from the source code.
 the docs are great, mind you, but having two sources to synchronize
just doesn't make sense (amazingly, the docs seem to be pretty
accurate, fred is doing an amazing job at monitoring source code
changes i guess).  it seems to me that auto-generated documentation
tools should really be part of python.

now, in that regards, one has to recognize that we currently have two
types of documentation:

a. reference docs, which can be auto-generated with pydoc

b. manual docs, which are written in LaTeX

could we unite both in some way?
this would be really useful for the code i write. 
one source, for code, and docs.

we might want to do something to couple the source code and the
written manual, e.g. where we could have a template that outlines the
"manual" versoin of the documentation, and our directive would go
fetch the docstring for the function or
class and insert it inline in our document automatically.  a class
documentation could look like this:

 intro and example text
 .. classdescref:: module.classname
 ..methoddescref:: module.classname.foo1
 ..methoddescref:: module.classname.foo2
 ..methoddescref:: module.classname.foo3
 ..methoddescref:: module.classname.foo4

this would allow arbitraty ordering of the methods (something which an
automated source to docs tool couldn't do) which is required to make
docs cleaner, and just fetching parts of the docstring, i.e. some code
shouldn't be reflected in user documentation.  looking at the current
python docs, it seems to me a bit difficult that the source files are
entirely separate from the source code.

also, one thing that i can't see is how to generate index entries from
docutils.  also, for typed references e.g. \function{foo}, i don't
know how you would do that in docutils.

anyway, that's a bit of a quick trigger email, maybe i should do more
due diligence to find out if that's been considered in the past... is
there some info somewhere about people trying to write the docs of
Python using docutils?  (and i'm not refering to pysource, rather to
convert the Python-<ver>/Docs directory)