[ZWeb] Organization of Zope API Reference

[Paul Winkler]

On Fri, Aug 27, 2004 at 08:24:04PM -0700, Don Hopkins wrote:
> I've gone through the Zope API reference and made an index of all the
> modules and classes, to stimulate discussion about how to improve the
> API reference. This is just a first cut to figure out what's there and
> how to approach indexing and categorizing it. 

You are probably not aware that I have made some very tentative
steps on cleaning up the API reference for the 2.7 edition
of the Zope Book.
See: http://www.plope.com/Books/2_7Edition/AppendixB.stx

Also, once we've addressed the short-term problem of having no 
good 2.7 API reference, I want to tackle the long-term issues in this 
proposal:
http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference
 
> Most modules in the API reference only contain one class of the same
> name, but a few modules have no classes or one or more differently named
> classes. So maybe it would be better to have a class name index, but
> indexing modules without classes as if they were classes.

I kinda like that idea.  So something like "module AccessControl"
would be unchanged, but "class DTMLDocument(ObjectManagerItem, 
PropertyManager)" would be a top-level entry, and its current
parent, "module DTMLDocument", would be removed?
 
> This list doesn't look complete to me. I think there are probably a
> bunch more classes that should be documented in the API reference, but
> here are the ones that are currently documented. 

Yes, if you think of any more that are missing, please add them
to:
http://dev.zope.org/Wikis/DevSite/Proposals/IdentifyMissingStuff
(part of the afore-linked proposal).
 
> This list is just a straw man to stimulate discussion of how to
> reorganize the API reference, so please feel free to suggest changes. 

I do like your "Exclusive" categorization.
Maybe we could somehow annotate each class name with one of your terms?
e.g.

class 'DTMLDocument' *(content)*

The terms get a little fuzzy with Python Scripts which are what
Jim might call "software in content space."
I'm not sure "content" is really always right, but I can't
think of a better at the moment.

I'm not crazy about the "modifier" categories.
That seems way too subjective.  

I did add an XXX note to myself in the 2.7 API ref that
PropertySheets are mostly used for ZClasses and should be
mentioned as such.

-- 

Paul Winkler
http://www.slinkp.com