.rst .pdf

Contents

zopeext for Sphinx

author

Michael McNeil Forbes <mforbes@alum.mit.edu>

This extension provides an autointerface directive for Zope interfaces.

Requirements

• Sphinx: pip install sphinx

• zope.interface: pip install zope.interface

• sphinxcontrib.zopeext: pip install sphinxcontrib-zopeext

Usage

In the build configuration file (the conf.py in your Sphinx documentation directory) add sphinxcontrib.zopeext.autointerface to your extensions list:

extensions = [..., 'sphinxcontrib.zopeext.autointerface', ...]

Then, in your documentation, use autointerface as you would use autoclass. You can refer to the interface with the :py:interface: role example.IMyInterface as you would use the :py:class: role to refer to the implementation example.MyImplementation.

Here is an example produced by the following code:

.. automodule:: example
   :show-inheritance:
   :inherited-members:

Example (click on the “[source]” link at the right to see the code)

Example module using zope.interface.

Here we define an interface IMyInterface and an implementation MyImplementation.

interface example.IMyInterface(x)

Bases: zope.interface.Interface

This is an example of an interface.

The constructor should set the attribute x.

Parameters

x (float) – The parameter x.

equals(x)

A required method of the interface.

Parameters

x (float) – The parameter x.

Notes

The argument self is not specified as part of the interface and should be omitted, even though it is required in the implementation.

x

A required attribute of the interface

interface example.IMySecondInterface(x)

Bases: example.IMyInterface

A refinement of the previous interface.

The constructor should set the attribute x.

Parameters

x (float) – The parameter x.

equals(x)

A required method of the interface.

Parameters

x (float) – The parameter x.

Notes

The argument self is not specified as part of the interface and should be omitted, even though it is required in the implementation.

x

A required attribute of the interface

y

A new required attribute

class example.MyImplementation(x, y=3.0)

Bases: object

Example

>>> a = MyImplementation(x=2.0)
>>> a.equals(2.0)
True

Constructor.

Parameters

• x (float) – The parameter x.

• y (float, optional) – An additional parameter y that is not part of the interface, but which has a default value (3.0) and so does not violate the interface definition.

equals(x)

A required method of the interface.

Parameters

x (float) – The parameter x.

Note

We have included the autointerface.css which simply adds the following rule to give a green background for the interface:

dl.interface > dt { background-color: #33FF33; }

One can also limit which members are displayed, just as you would with .. autoclass:

.. autointerface:: example.IMyInterface
   :members: x, equals
.. autoclass:: example.MyImplementation
   :members: x, equals

Example (click on the “[source]” link at the right to see the code)

interface example.IMyInterface(x)

This is an example of an interface.

The constructor should set the attribute x.

Parameters

x (float) – The parameter x.

equals(x)

A required method of the interface.

Parameters

x (float) – The parameter x.

Notes

The argument self is not specified as part of the interface and should be omitted, even though it is required in the implementation.

x

A required attribute of the interface

class example.MyImplementation(x, y=3.0)

Example

>>> a = MyImplementation(x=2.0)
>>> a.equals(2.0)
True

Constructor.

Parameters

• x (float) – The parameter x.

• y (float, optional) – An additional parameter y that is not part of the interface, but which has a default value (3.0) and so does not violate the interface definition.

equals(x)

A required method of the interface.

Parameters

x (float) – The parameter x.