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 ________________________________________________________________________