[Zope-dev] RE: api docs [Was: Re: Post-mortem ...]

[Brian Lloyd]

> What is the Right Way to keep api docs in sync?
> 
> 
> Example 1:
> 
> ZCatalog/IZCatalog.py seems to be more up to date, but 
> ZCatalog/help/ZCatalog.py is used by the Zope Help System and I guess 
> also to generate api docs.
> 
> 
> Example 2:
> 
> I did add OFS/IOrderSupport.py, but how will it become part of help and 
> api docs? Is there a better way than copying it to OFSP/help? I hate to 
> add redundant code because - as example 1 shows - it is hard to keep the 
> files in sync.
> 
> 
> CMF uses the interface files also as help files. As interface files 
> become more and more common in Zope it might make sense to do the same 
> in Zope.

Ghaaa... :( API docs come from OFSP/help, so you'll probably have to 
copy it for now. As you rightly pointed out, this is problematic for 
keeping things in sync, but we should hold our nose for now and do 
it, since it's too late in the 2.7 cycle to contemplate that big a 
restructuring.

Making this sane would be a good potential project for an enterprising 
zopista for 2.8... 


Brian Lloyd        brian at zope.com
V.P. Engineering   540.361.1716              
Zope Corporation   http://www.zope.com