(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.
pydocgen
Description: Binary data
gentest.py
Description: Binary data
_______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
