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

[Martin Blais]

(sorry i sent this by mistake, d**n gmail doesn't have a
confirm-before-send feature,
completing below...)

(2)
> 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

problems with (a):
- full reference to all the stuff in a module file is often
inadequate, there is too much informatino, lots of irrelevant stuff
- no space for examples and other kinds of explanations
- ordering is source-code based, which is not the best for documentation

> b. manual docs, which are written in LaTeX
- they're great, but they live in a separate file!
- some duplication of information that is available in docstrings


i wrote a little prototype idea in 10 minutes to demonstrate what i
mean, download the attached script and run it on the attached module. 
this is really just jotted down quickly, much work would have to be
done on this for it to be usable, but it demonstrates the idea.

basically, the idea would be to add a special string for each module,
whose role would be to patch together the various docstirngs available
in the module in a way that is readable and that exposes only what is
needed.   this way the Python modules documentation could probably be
integrated in the source code... wouldn't that make sense?

any thoughts appreciated.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pydocgen
Type: application/octet-stream
Size: 2519 bytes
Desc: not available
Url : http://mail.python.org/pipermail/doc-sig/attachments/20050420/af4c0a36/pydocgen.obj
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gentest.py
Type: application/octet-stream
Size: 2615 bytes
Desc: not available
Url : http://mail.python.org/pipermail/doc-sig/attachments/20050420/af4c0a36/gentest.obj