[Zope] Suggestion for standard Product documentation mechanism

[Jim Harrison]

There's been a good bit of discussion about Zope documentation on the list
recently, and improved documentation of the core Zope distribution would
certainly be a great thing. However, part of the attraction of Zope are the
available extensions in the form of Zope Products. Documentation for these
is also important, whether they're being used as is or as a basis for
customization, but it's very difficult for these authors to commit the time
required to create separate docs. As a result, it's difficult to figure out
the structure and workings of most Products. To make Product documentation
easier, I propose the following:

When a product is installed, there should be a standard mechanism that
creates a "Doc" tab with a page containing information compiled from the
Product distribution.

The first element on the doc page should be a brief overview of the Product,
which would be taken from a text or html file in the product directory with
a standard name (docs!.html or docs!.doc, for example).

The second element should be a listing by name of all dtml pages and methods
in the Product with brief explanatory text. The text should be derived from
the contents of a dtml tag in each page that functions like a doc string
(perhaps a <dtml-doc> tag).

The third and last element should be a listing by name of all python modules
in the Product with each name followed by the doc string of the module.

Indented under each module should be a listing of all callable top level
functions in the module with the corresponding doc strings and all classes
with their doc strings.

Indented under each class should be all callable functions within the class,
with their doc strings.

Thus at import, the names and doc strings of the elements of the Product
would be extracted and collected into a doc page with this organization:

Brief description (from file)
DTML Page(s) -- each with "dtml doc string"
DTML Method(s) -- each with "dtml doc string"
FirstPythonModuleName -- doc string
   Func def 1 -- doc string
   Func def 2 -- doc string
   Class def 1 -- doc string
      Class func 1 -- doc string
   Class def 2 -- doc string
SecondPythonModuleName -- doc string
etc.

This approach to documentation has the advantage of exposing the overall
structure of a Product in addition to documenting its internals. Having the
documentation method use doc strings makes it easier to maintain brief but
useful documentation and keep that documentation up to date as code is
revised. Of course there would need to be some guidelines about how to set
up the doc strings (the standard python format would be a decent start) and
conventions such as showing what imports what in module doc strings might be
helpful.

I got started thinking about this when I was trying to customize Squishdot
in some fairly simple ways, but ended up having to bother the author (who
was very helpful) about where certain functionality was located. While the
approach I suggest here doesn't completely take the place of well-written
standalone documentation, it could provide a lot of information with
substantially less effort, is easier to maintain in the setting of iterative
code development, and is consistent with the open source concept of multiple
authors extending code's functionality.

Jim Harrison
________________________________________________________________________
James H. Harrison, Jr., MD, PhD
University of Pittsburgh Health System
C920 PUH, 200 Lothrop Street
Pittsburgh, PA 15213

jhrsn@pop.pitt.edu | voice: 412-647-5529 | fax: 412-647-9588

"If you want sense, you'll have to make it yourself!!"-Norton Juster
________________________________________________________________________