Jim has a simple tool to convert doc strings to a UNIX man page
like document... This idea could be extended
simmilar work doc_collect by daniel larsson
reads python and generates manuals
class for def statements become headings with the doc strings
as section bodies
minimal source parsing to get class and function defs
Jim was looking specifically at extension modules
produces one manual page per/modules
section for module functions
each function or method is a sub-section
if doc string is of the form...
"""spam(a,b) -- description of spam"""
...you can do something meaningful
problem: extension modules need to export types
problem: need to be able to get at method doc strings
without creating instances
Proposal: create a "method list" type
method list object pointers could optionally be created
by extension modules and a pointer put in the type object struct
Method list object requrements
get and store method names, function pointers, more...
Anything more? Organization? format markup? structure markup?
Is it critical for doc strings to be readily available in the
interpreter? So if explicit markup is used, then we need to
provide standard formatting tools within the interpreter
Guido: conclusion is that we'll never agree on a convention
for structured markup
Guido: The first line of the docstring is a complete sentence
describing the function so tools like apropos will work
Two types of doc strings
those for users of the functions
those for maintainers of the functions
Guido: I suggest making Jim's tool available outside of USGS.
The quality of the documentation will improve if people have
live examples to work with