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:
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