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