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

[seb bacon]

At the risk of stating the obvious, are you folks aware that pydoc comes
with python these days?  It produces javadoc-like html as well as man
pages (try pydoc pydoc from a prompt to see what I mean)

A little tool that everyone should know of.

seb


On Wed, 2002-04-03 at 15:35, Chris McDonough wrote:
> > 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.
> 
> They almost certainly will be.
> 
> > 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.
> 
> Ah ok.  Well, all the tools are available to whatever motivated 
> individual wants to generate docs from source.
> 
> > 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...
> 
> Hopefully being able to comment on the online version of the API docs 
> will help us figure out what's missing.
> 
> Thanks!
> 
> -- 
> Chris McDonough                    Zope Corporation
> http://www.zope.org             http://www.zope.com
> "Killing hundreds of birds with thousands of stones"
> 
> 
> _______________________________________________
> Zope maillist  -  Zope@zope.org
> http://lists.zope.org/mailman/listinfo/zope
> **   No cross posts or HTML encoding!  **
> (Related lists - 
>  http://lists.zope.org/mailman/listinfo/zope-announce
>  http://lists.zope.org/mailman/listinfo/zope-dev )