There has never been a coordinated doc-sig effort started for automated documentation generation ala gendoc. Currently gendoc has been patched to work in 1.5 by it's author Daniel Larsson. I have wanted to start one though. Hopefully recent interest indicates that we would get some substantial efforts from folks on this list should we start one. So... Dan and I have bounced some preliminary thoughts on just how such a gendoc "next generation" (1.0) tool should work. I'd like to propose the following and start hammering on a detailed design for gendoc NG. If the design proves to be sufficiently modular we'll be able to divide up the work among several people. There's a lot of work here but I'm confident we can come up with something working/nice in a couple months. Remember, this is a draft for discussion, so pile on the constructive comments;-) GENDOC 1.0 Design Requirements Works for Python 1.5 and up. (takes advantage of new features like issubclass()) Parsing using new re module. Supports 1.5 Package scheme and is written as a package. Uses import method to extract info. Uses Structured Text as standard for doc string parsing. (Although we have to decide on the prototype information format.) Supports C modules/types that have doc strings. Generates abstract information structure which can be tapped by rendering classes to generate customizable output. Abstract structure is picklable using cPickle. (Speeds tailoring the rendered output while keeping the input the same.) Merge output from independant runs. (simple using prior pickle files) Must run on Unix, Win32, and Mac. QUESTIONS - How to do function prototypes? Resort to Python source parsing module? GENDOC 1.0 Architecture Objects: Package, Module, Class, Function, Method, Attribute, Argument, Documentation, Hyperlinks, ... Each of these will store information derived from their doc strings and other sources. Parse doc strings with structured text and populate Documentation class instance for each doc string. Class objects contain instances from Method, Attribute, Documentation, along with base class references. Class and Module objects also get added to separate heirarchy structures supporting dependancy diagrams. Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text, etc. Renderers are passed the full structure object and walk the tree generating the appropriate output. Features to help tailor the content and ordering of output may be included in a base class AbstractRenderer. A renderer which translates the data into a structure suitable for import into a programming environment tool like PTUI might me nice too. This obviously moves much of the complexity to the rendering classes but with helper base classes and good examples people ought to be able to write their own without too much trouble. The next step would be to define the doc objects' interfaces. A quick shot: class Package: def filename(): ... Or as separate functions(def functions():) -Yes def modules(): # can a package have functions? def subpackages(): def parent(): # None, if global def name(): def documentation(): # Returns Documentation object class Documentation: def brief(): # the brief one liner def body(): # return Body object def examples(): # return example text class Body: # return structure doc string as a list of # objects representing marked up text/hypertext class Module: def filename(): def children(): def parent(): def name(): def documentation(): class Function: def parent(): # the function's module def name(): def arguments(): def documentation(): def type(): #?? built-in or "normal" ---Jim F would go ballistic:-) def implementation(): # let's call it this. # Can we differentiate between builtin vs. extension? def return_type(): #?? If we can deduce this from a prototype doc # OK class Class: def parent(): def name(): def baseclasses(): def methods(): def documentation(): class Method(Function): # Basically the same thing, except parent() def parent(): # returns a Class (?) ---yes, class Attribute: def parent(): def name(): def type(): # type(attr) def value(): # If there is a notation in the module's docstring # to document attributes, then: def documentation(): class Argument: #--- how to handle *args and **kw ? def parent(): # Function object def name(): def type(): def default(): def documentation(): _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________