[ZWeb] Organization of Zope API Reference
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.
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.
More information about the Zope-web