[Zope3-dev] Api reference & newbie tasks

[Jeffrey P Shell]

On Dec 27, 2003, at 7:32 PM, Shane Hathaway wrote:

> On Fri, 26 Dec 2003, Stephan Richter wrote:
>
>> On Saturday 13 December 2003 14:23, Iwan van der Kleyn wrote:
>>> So I decided to run Epydoc on the CVS
>>> source. I noticed that inline documentation of the source is, well,
>>> rather sparse.  Are there any initiatives to correct this? And epydoc
>>> fails to include interfaces in the generated documentation. Anyone 
>>> got a
>>> fix for this? Otherwise I'll will pick it up and try to locate and 
>>> fix
>>> the problem.
>>
>> Well, all API documentation really lies in the interfaces. We often 
>> do not
>> document implementations, since you get hung up on unimportant 
>> details. The
>> second very important part of an API reference is the ZCML reference, 
>> since
>> it glues the components together and tells you how things work.
>
> +1.  I've been hunting for some documentation generation tool that's at
> least minimally aware of "Scarecrow" interfaces like Zope's and have 
> found
> nothing at all.  Epydoc could do a lot better.

It would be nice if it could - I like epydoc's output, and I like that 
it understands reStructuredText.  I only wish I could get it working 
easily with Zope 2 so I can get sic it at my current project.