Code Module specific apidoc Directives

The apidoc:rootModule Directive

The rootModule directive allows you to register a third party Python package with apidoc’s code browser.

Before we can register a new root module, we need to load the metaconfiguration:

>>> from zope.configuration import xmlconfig
>>> import zope.app.apidoc.codemodule
>>> context = xmlconfig.file('meta.zcml', zope.app.apidoc.codemodule)

Now we can run the directive. First, let’s make sure that no root modules have been registered yet:

>>> from zope.component import getUtilitiesFor
>>> from zope.app.apidoc.codemodule.interfaces import IAPIDocRootModule
>>> list(getUtilitiesFor(IAPIDocRootModule))
[]

Now run the registration code:

>>> context = xmlconfig.string('''
...     <configure
...         xmlns="http://namespaces.zope.org/apidoc">
...       <rootModule module="zope" />
...     </configure>''', context)

and the root module is available:

>>> list(getUtilitiesFor(IAPIDocRootModule))
[('zope', 'zope')]

The apidoc:importModule Directive

The importModule directive allows you to set the __import_unknown_modules__ flag of the class registry. When this flag is set to false, paths will only be looked up in sys.modules. When set true, and the sys.modules lookup fails, the import function of the class registry tries to import the path. The hook was provided for security reasons, since uncontrolled importing of modules in a running application is considered a security hole.

By default the flag is set to false (of course, this depends on the order in which tests are run and what ZCML has been configured or if this was manually changed, so we can’t really rely on the default here):

>>> from zope.app.apidoc import classregistry
>>> classregistry.__import_unknown_modules__ = False

We can now use the directive to set it to true:

>>> context = xmlconfig.string('''
...     <configure
...         xmlns="http://namespaces.zope.org/apidoc">
...       <moduleImport allow="true" />
...     </configure>''', context)

>>> classregistry.__import_unknown_modules__
True

We can also set it back to false of course:

>>> context = xmlconfig.string('''
...     <configure
...         xmlns="http://namespaces.zope.org/apidoc">
...       <moduleImport allow="false" />
...     </configure>''', context)

>>> classregistry.__import_unknown_modules__
False