[Zope] Suggestion for standard Product documentation mechanism

[Patrick Phalen]

[Jim Harrison, on Sun, 12 Dec 1999]
:: 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.

Which makes me wonder if there's a future opportunity to incorporate
the XML output in Amos/Pam's Docbook XML plans.

<snip>

:: 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. :-)

Hmm. This is pure conjecture and I don't have time right now to research
this now,  but ... have you looked at the IDLE CVS tree? The Class
browser and help button features might have the seed of an idea for
this?

:: 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.

Yes. Automating docs would be A Good Thing(TM).