Text File
directives.txt

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))
[(u'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 sus.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:

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