[ZWeb] Organization of Zope API Reference

Paul Winkler pw_lists at slinkp.com
Sun Aug 29 02:29:33 EDT 2004

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 
> 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
(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?

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

More information about the Zope-web mailing list