[DOC-SIG] Status of documentation effort?

[Friedrich, Robin K]

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
_______________