[Zope] Suggestion for standard Product documentation mechanism

[Jim Harrison]

on 12/11/99 4:19 AM, Patrick Phalen at zope@teleo.net wrote:

> This sounds very useful. Guido van Rossum would undoubtedly be
> overjoyed to see someone using docstrings for their intended purpose. :)
> 
> I wonder if Daniel Larsson's gendoc or pythondoc could be put to use for
> it: http://starship.skyport.net/crew/danilo

pythondoc looks pretty good for generating documentation from the modules of
a product, particularly since its output is already available as either HTML
or XML. This would need to be integrated into Zope in a standard way, plus
we would need a similar mechanism for documenting dtml pages/methods that
are included in a Product. I suppose the strategy would be to create a top
level routine that looked in the product's directory for a standard summary
doc file, examined each dtml method/page file for doc strings (tagged as
suggested previously), and then called pythondoc for each python module.
Even if no doc strings were present, this would give you a very useful
readout of the structure of a Product and a guide to reading the code.

Perhaps it's going a bit too far to suggest that each module/function/class
definition name could be linked to a search routine that returned the text
of the item in a separate window when its name was clicked. :-)

The important point of this mechanism is that it would be a standard,
developer-friendly approach that inherently reflected the structure of the
code and was straightforward to keep up-to-date as the code evolved. I think
the ongoing documentation discussions on the list show that we really need
something like this.

Jim
________________________________________________________________________
James H. Harrison, Jr., MD, PhD
Associate Director of Pathology Informatics, Department of Pathology
Faculty Member in Residence, Center for Biomedical Informatics
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
________________________________________________________________________