[Zope] ZPT file reader

[Paul Winkler]

On Tue, Nov 11, 2003 at 04:40:08PM +0100, Andreas Jung wrote:
> 
> 
> --On Dienstag, 11. November 2003 10:24 Uhr -0500 Paul Winkler 
> <pw_lists at slinkp.com> wrote:
> 
> >On Tue, Nov 11, 2003 at 12:40:45AM -0800, Dennis Allison wrote:
> >>
> >>Please take a look at The Zope Book (2_6 Edition).  The Appendices
> >>contain the API for Zope.  The book itself contains a wealth of
> >>infomration. The help files are another useful source of information.
> >>When all else fails,  read the code.
> >
> >The Zope API Reference, useful as it is, is far from complete.
> >For example, it does not answer the O.P.'s question.
> 
> This raises my old question: why aren't there people in the community
> willing to contribute to the documentation? Other projects have less
> problems in producing a reasonable up-2-date documentation.
> It is only a problem of the Zope community? I really don't understand 
> this...

We talked a bit about the API reference during the 2.6 Zope Book process.
As I recall, the problems were partly logistical.
the Zope Book has embedded comments, and we don't want to lose those.
On the other hand, the API reference was IIRC originally generated from 
the Help system.  So there's an impedance mismatch there.
You don't want to make a change in the API reference without
making the same change in the embedded docs; this requires developer
access to the Zope sources.

These problems are surely not insoluble, but nobody's had the time 
and/or drive to deal with it.

Furthermore, it's rather odd that the embedded docs are only
semi-embedded.  What I mean is, they are not pulled from docstrings
of the actual classes, but from separate files in the help/ directories
scattered around the zope source tree, which can get out of sync with the 
real code. I guess this was done to allow developers a bit more leeway in 
what they do with their docstrings?  Or to avoid cluttering up the API 
reference with stuff that is meant to be purely internal? But it leads to 
weird historical cruft like ObjectManagerItem (my favorite API reference 
gripe), an imaginary class that exists only in the docs.

-- 

Paul Winkler
http://www.slinkp.com
Look! Up in the sky! It's PREDOMINANT SPAZ!
(random hero from isometric.spaceninja.com)