ChangeLog

This file describes user-visible changes between the extension versions.

Version 0.2.1 (2013-05-01)

• Removed automatic import of autointerface to facilitate setup. New code must now import sphinxcontrib.zopeext.autointerface explicitly.

Version 0.2 (2012-07-24)

• Added website.
• Added documentation.
• Added to PyPi.
• Added example.py

Version 0.1 (2010-05-20)

• Initial version.

Details

autointerface

This Sphinx extension adds an autointerface directive, which can be used like autoclass to document zope interfaces. Interfaces are intended to be very different beasts than regular python classes, and as a result require customized access to documentation, signatures etc.

.. autointerface::

The autointerface directive has the same form and option as the autoclass directive:

.. autointerface:: IClass
   ...

See also

sphinx.ext.autodoc

Note

This extension also serves as a simple example of using the sphinx version 0.6 sphinx.ext.autodoc refactoring. Mostly this was straight forward, but I stumbled across one “gotcha”:

The objtype attribute of the documenters needs to be unique. Thus, for example, InterfaceMethodDocumenter.objtype cannot be ‘method’ because this would overwrite the entry in AutoDirective._registry used to choose the correct documenter.

Implementation Details

interface_getattr(*v)	Behaves like getattr but for zope Interface objects which
interface_format_args(obj)	Return the signature of an interface method or of an
InterfaceDocumenter(directive, name[, indent])	A Documenter for zope.interface.Interface interfaces.
InterfaceAttributeDocumenter(directive, name)	A Documenter for zope.interface.interface.Attribute
InterfaceMethodDocumenter(directive, name[, ...])	A Documenter for zope.interface.interface.Attribute
InterfaceDirective(name, arguments, options, ...)	An ‘interface’ directive.
setup(app)

class sphinxcontrib.zopeext.autointerface.InterfaceAttributeDocumenter(directive, name, indent=u'')

A Documenter for zope.interface.interface.Attribute interface attributes.

class sphinxcontrib.zopeext.autointerface.InterfaceDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

An ‘interface’ directive.

class sphinxcontrib.zopeext.autointerface.InterfaceDocumenter(directive, name, indent=u'')

A Documenter for zope.interface.Interface interfaces.

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be none).

class sphinxcontrib.zopeext.autointerface.InterfaceMethodDocumenter(directive, name, indent=u'')

A Documenter for zope.interface.interface.Attribute interface attributes.

sphinxcontrib.zopeext.autointerface.interface_format_args(obj)

Return the signature of an interface method or of an interface.

sphinxcontrib.zopeext.autointerface.interface_getattr(*v)

Behaves like getattr but for zope Interface objects which hide the attributes.

Note

Originally I simply tried to override InterfaceDocumenter.special_attrgetter() to deal with the special access needs of Interface objects, but found that this is not intended to be overwritten. Instead one should register the special accessor using app.add_autodoc_attrgetter().

License

If not otherwise noted, the extensions in this package are licensed
under the following license.

Copyright (c) 2009 by the contributors (see AUTHORS file).
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.