[Zope3-dev] Towards better API documentation...

[Jim Fulton]

I think Stephan is right to focus on the introspector.  Some notes:

- The introspector is an on-line tool. It has the potential to
   provide an extremely valueable interactive API and system
   discovery tool.  A lot of work is needed to realize it's potential.
   This is a great task for people to volunteer on

   I'd be happy to provide support to this work in the form of advice and
   needed architectural support.

   The configuration of a zope system is dynamic. The things you can do with
   an object depends on the system configuration, which, can vary over time.
   This makes an on-line tool, rather than an off-line tool, especially
   useful.

- Having said the above, it would be nice if there was an option to
   interactively generate pdf output of specific interfaces, classe, etc.,
   for printing.

- The introspector currently relies on the interface service to
   do most of it's work.

   Murthy K. Narasimha and Suresh Babu Eddala are working on moving the
   interface browsing view from the interface service to the site manager.

   Any work done on this in the short term should be coordinated with them.

Jim

Stephan Richter wrote:
> Hello everyone,
> 
> I started thinking about developing a tool that will give us some better API 
> documentation. As we all know, common Python documentation tools work not 
> very well on Zope 3 code, because
> 
> (a) they do not handle interfaces.
> 
> (b) they are unaware of the component architecture, which provides useful 
> information, such as adapters for a given interface.
> 
> First off, I am not so interested in discussing the output of the tool. I do 
> not care whether it will generate static or dynamic HTML documentation, STX 
> or LaTeX; in fact, I would like to do all combinations at some point.
> 
> Interface Documentation
> -----------------------
> 
> The interface documentation is and will be the central point of the API 
> documentation. However, I think the current introspector does not provide as 
> much information as it could. Here is a list of pieces of information I would 
> like to have (including existing ones)
> 
> 1. Documentation of all attributes/properties and methods. The introspector 
> currently does a good job with that.
> 
> 2. What adapters exist for this interface. This is two-fold, as I want to ask
> 
>   (a) Give me all Adapters that that exist for this interface.
> 
>   (b) Give me all Adapters that provide this interface.
> 
> 3. A list of views defined for this interface should be optionally included 
> too.
> 
> 4. Optionally have a line saying whether this interface is used as a service 
> or utility.
> 
> 
> Class Documentation
> -------------------
> 
> I think the current version of the introspector does pretty good here with the 
> standard API. More specific information, such security, views and so on are 
> better placed into Content Component documentation, since it is not 
> applicable to all classes.
> 
> 
> Service Component Documentation
> -------------------------------
> 
> This is simply a list of all available services by name and links to the 
> characteristic interface.
> 
> Content Component Documentation
> -------------------------------
> 
> A list of of all content components should be provided with the following 
> info.
> 
> 1. There should be a link to the class of the component.
> 
> 2. Display factory information.
> 
> 3. Display security information
> 
> 4. Display views defined for the content.
> 
> 
> Did I forget anything? 
> 
> While the information is available, it might not be accessible. I checked the 
> Adapter Service, Factory Service and the Service Manager and they have 
> methods to access information as we need them. The Presentation Service, on 
> the other hand, has a totally useless (read broken) "getRegisteredMatching()" 
> method that does not even have a "return" call. Other than that it does not 
> allow us to look for all available views of an interface.
> 
> I'd appreciate any input you might have.
> 
> Regards,
> Stephan


-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org