Overview¶
This Zope 3 package provides fully dynamic API documentation of Zope 3 and registered add-on components. The package is very extensible and can be easily extended by implementing new modules.
Besides being an application, the API doctool also provides several public APIs to extract information from various objects used by Zope 3.
utilities – Miscellaneous classes and functions that aid all documentation modules. They are broadly usable.
interface – This module contains functions to inspect interfaces and schemas.
component – This modules provides utility functions to lookup components given an interface.
presentation – Presentation components are generally more complex than others, so a separate utilities module is provided to inspect views.
classregistry – Here a simple dictionary-based registry for all known classes is provided. It allows us to search in classes.
Using the API Dcoumentation¶
The APIDocumentation
class provides
access to all available documentation modules. Documentation modules
are utilities providing IDocumentationModule
:
>>> from zope import component as ztapi
>>> from zope.app.apidoc.interfaces import IDocumentationModule
>>> from zope.app.apidoc.ifacemodule.ifacemodule import InterfaceModule
>>> from zope.app.apidoc.zcmlmodule import ZCMLModule
>>> ztapi.provideUtility(InterfaceModule(), IDocumentationModule,
... 'Interface')
>>> ztapi.provideUtility(ZCMLModule(), IDocumentationModule, 'ZCML')
Now we can instantiate the class (which is usually done when traversing ‘++apidoc++’) and get a list of available modules:
>>> from zope.app.apidoc.apidoc import APIDocumentation
>>> doc = APIDocumentation(None, '++apidoc++')
>>> modules = sorted(doc.keys())
>>> modules
['Interface', 'ZCML']
>>> doc['ZCML']
<zope.app.apidoc.zcmlmodule.ZCMLModule 'ZCML' at ...>
Developing a Module¶
Implement a class that realizes the
IDocumentationModule
interface.Register this class as a utility using something like this:
<utility provides="zope.app.apidoc.interfaces.IDocumentationModule" factory=".examplemodule.ExampleModule" name="Example" />
Take care of security by allowing at least
IDocumentationModule
:<class class=".ExampleModule"> <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" /> </class>
Provide a browser view called
menu.html
.Provide another view, usually
index.html
, that can show the details for the various menu items.
Note: There are several modules that come with the product. Just look in them for some guidance.
New Static APIDOC-Version¶
An alternative APIDOC-Version is available through ++apidoc++/static.html
Find and Tree are implemented in Javascript, so it should be possible to do a
“wget” - Offline-Version of APIDOC.
In fact, this package comes with a somewhat smarter version of “wget” that can load a Zope configuration and export the documentation. For more information, see Exporting Static HTML Documentation.