[Zope] Use the source Luke -- what could be done to help documentation process? Request for comments!

[Oliver Bleutgen]

Thanks for taking your time to answer.

Chris McDonough wrote:
>>perhaps a dumb question, but would it be feasible to create the API-docs
>>straight from the source? OFS/Propertymanager.py is a nice example of a
>>doc-string. A tool like Dieter Maurer's docfinder shows how good incode
>>documentation can be very valuable.
>>
> 
> It would be.  Doug Hellmann's HappyDoc could be used.  I'm not entirely
> certain that the result would be useful, because you'd need to wade through
> tons of cruft to get to the "good stuff".  This is why there is interface
> documentation... to separate the "private" stuff from the "public" stuff.
> 
> Interfaces, though they're manual currently and largely only used for docs
> in Zope 2, play a crucial functional role in Zope 3.  This will make a huge
> impact on their usefulness as documentation because they need to be kept up
> to date for the system to function properly.

This is definately something which will greatly improve the work of 
product authors and others. Though I have no right to demand something 
from the people working on zope 3, it would IMO be great if zope3's 
API-docs could be based on the source of the interfaces.
There is already a happydoc'ed zope documentation at
http://www.zope.org/Documentation/Developer/ZopeSrcDocs
for instance, though it's 2.3.2 only.
I'm not familiar how happydoc works, but perhaps it's possible to use 
just the interfaces right now, or to switch the output to be less 
verbose - similar like the api-doc is right now. Or, hopefully, it 
wouldn't be too much work to adapt happdoc to zope's needs.
<wet developer dream>
Or integrate a "zhappydoc" with zope to generate the api-docs for zope's 
HelpSys automatically, *including* all installed products.
</wet developer dream>
What would be needed though is a short description of the arguments of 
methods in the doc-strings.

> 
> All this, said, if someone wanted to devise a system that allowed you to
> upload a Zope release tarball (or a checkout from CVS) and run HappyDoc
> against it to get HTML files and put them up for browsing, I'm sure it would
> be useful to a lot of folks.

Well, obviously somebody has done it, once. I gave it a try some time 
ago, failed, and didn't have the time to persue. I did know nothing 
about happydoc.

> 
> 
>>This could perhaps be combined with a talkbacked source browsing feature
>>on zope.org. Everytime I have to dive really into the source to find out
>>what happens with my arguments (take ZCatalog.ZopeFindAndApply as an
>>example) I wish I could have some possibility to conserve what I found
>>
> out.
> 
> Would having the API reference in BackTalk be a start towards this?

This would be great, even if zope 3 is out, IMO, because it could help 
commiters to gather missing material. Eventually one could account 
missing/faulty interface comments as (noncritical) bugs, whereby there 
should be written guidelines as to what has to be in said comments (e.g. 
"has to include description of arguments"). So the collector would get a 
nice tool to keep the API docs in shape.

> [java api docs example]
> 
> Have you seen the API reference in the Zope Book and the Help System?  It's
> maybe not as comprehensive, but this is its goal.  How can it be improved?

Unfortunatly I'm still stuck mainly at zope 2.3.3 and didn't do too much 
with newer zopes, although IIRC the API docs in HelpSys didn't change.
I like the API reference in the Help System very much, esp. it's layout 
is better IMO than the online version of the zope book, but both are not 
complete (as a search for ZopeFind reveals).
But, I use the API doc in zope for nearly 30% of my information needs, 
60% is reading zope's source and the rest is mailing lists etc..
With a more or less complete API documentation this could be shifted to 
80%/10% I estimate. Fortunatly python source is very readable...

cheers,
oliver