[Zope-dev] New Help System in 2.2

[Martijn Faassen]

Paul Everitt wrote:
> 
> I can add a bit more background on the decision to have the API docs not
> rendered from the source.
> 
> First, Zope used to have an online help system that inspected the source
> and rendered documenation on the fly.  Very nice indeed.  But we yanked
> it.
> 
> Why?  The most primary reason is philosophical, a la Jim Fulton.  Jim
> believes strongly in the idea that interfaces are _not_ connected to
> implementation:
> 
>   http://www.zope.org/Members/jim/PythonInterfaces/Summary

I think it's more important that interfaces should be explicit, not 
implicit. They should be connected to the implementation all right; just
not *implicit* in the implementation. It would be very nice eventually
if the implementation could explicitly check whether an object
conforms to a certain interface though, and as far as I'm aware this is
also what Jim's saying.

> Thus, the new system is patterned after this philosophy.  The interface
> is the contract that one or more implementations should live up to.
> 
> Right now we aren't doing much of that which Jim described.  The
> interface is just a documentation artifact.  But it is philosophically
> consistent with what we'd ultimately like to do.

Ultimately I'd like to be able to say in the Zope sources loud and clearly
'this object conforms to THIS interface'. And then you'd have somewhere else
in the Zope sources the interface definition (which is also just in
Python source), which has documentation associated with it, probably
as a docstring in the code, though potentially also with a reference to
some file in another format.

And then you should generate the API documentation from that. I'd also
say that actually active source-wise implementation of this interface
philosophy is quite important for the long term viability of the Zope
sources. Otherwise the documentation (even of interfaces) will always
end up being behind the actual Zope sources, making it worth a lot
less.

Regards,

Martijn