Usage#

This extension adds support for documenting Event and Property objects automatically through the autodoc extension.

Configuration#

To enable this, “pydispatch_sphinx” must be included in the extensions list of your project’s conf.py:

extensions = [
    'sphinx.ext.autodoc',
    ...
    'pydispatch_sphinx',
]

To take full advantage of the extension, the intersphinx extension is recommended.

Add “sphinx.ext.intersphinx” to the extensions list:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    ...
    'pydispatch_sphinx',
]

And add the “python-dispatch” URL to intersphinx_mapping in conf.py:

intersphinx_mapping = {
    'pydispatch': ('https://python-dispatch.readthedocs.io/en/latest/', None),
    ...
}

Documenting Properties#

When used with the automodule or autoclass directive, any Property (or its subclasses) that have docstrings will be detected and their markup will be added using the autodispatcherproperty directive.

If PEP 484 type hints exist, they will be represented accordingly using the :type: option of autodispatcherproperty. If a default value is specified, it will also be included in the final output.

See the docstring examples below with their corresponding reStructuredText output.

Property Objects#

Python Docstring

from pydispatch import Dispatcher, Property

class Foo(Dispatcher):
    """Summary line.
    """

    # This will not include any specific type information
    prop_a = Property()
    """Description of prop_a
    """

    # This will include type information and a default value
    prop_b: int = Property(0)
    """Description of prop_b
    """

HTML Output

class Foo(*args, **kwargs)[source]#

Summary line.

Property prop_a = None#

Description of prop_a

prop_a is a pydispatch.Property object.

Property prop_b: int = 0#

Description of prop_b

prop_b is a pydispatch.Property object.

Container Properties#

Python Docstring

from typing import List, Dict, Any
from pydispatch import Dispatcher, Property, ListProperty, DictProperty

class Bar(Dispatcher):
    """Summary line.
    """

    # This will not include any specific type information
    prop_a = ListProperty()
    """Description of prop_a
    """

    # This will include type information
    prop_b: List[int] = ListProperty()
    """Description of prop_b
    """

    # This will include type information and a default value
    prop_c: Dict[str, Any] = DictProperty({'foo': 'bar'})
    """Description of prop_c
    """

HTML Ouput

class Bar(*args, **kwargs)[source]#

Summary line.

ListProperty prop_a#

Description of prop_a

prop_a is a pydispatch.ListProperty object.

ListProperty prop_b: List[int]#

Description of prop_b

prop_b is a pydispatch.ListProperty object.

DictProperty prop_c: Dict[str, Any] = {'foo': 'bar'}#

Description of prop_c

prop_c is a pydispatch.DictProperty object.

Documenting Events#

Documenting Events is similar to documenting properties, except events are not defined individually at the class level. See here for details.

The event and autoevent directives are used to represent Events.

Attribute Annotation#

To include events in your documentation, annotations may be added to the class body with the event name to document as the attribute and Event as its type.

Python Docstring

from pydispatch import Dispatcher, Event

class Baz(Dispatcher):
    """Summary line
    """

    _events_ = ['event_a']

    event_a: Event
    """Description of event_a
    """

HTML Ouput

class Baz(*args, **kwargs)[source]#

Summary line

Event event_a#

Description of event_a

event_a is a pydispatch.Event object.

Method Annotation#

Another method of documenting events is to define a method with the same name as the event. This also allows you add type hints for the event.

Python Docstring

from typing import Optional
from pydispatch import Dispatcher

class Spam(Dispatcher):
    """Summary line
    """

    _events_ = ['value_changed']

    def value_changed(self, new_value: int, old_value: Optional[int], **kwargs):
        """Description of value_changed
        """
        pass

HTML Ouput

class Spam(*args, **kwargs)[source]#

Summary line

Event value_changed(new_value: int, old_value: Optional[int], **kwargs)[source]#

Description of value_changed

value_changed is a pydispatch.Event object.

Cross Referencing#

Property objects may be referenced by the py:dispatcherproperty role and Events referenced by the py:event role.

Note that “property” was not chosen as a role name to avoid conflicts with the built-in property decorator.

For convenience though (since dispatcherproperty is quite a long name), both may be referenced using the py:attr role.

From the examples above, Foo.prop_a can be referenced using

:dispatcherproperty:`Foo.prop_a`: Foo.prop_a
:attr:`Foo.prop_a`: Foo.prop_a
:obj:`Foo.prop_a`: Foo.prop_a

And Baz.event_a can be referenced using

:event:`Baz.event_a`: Baz.event_a
:attr:`Baz.event_a`: Baz.event_a
:obj:`Baz.event_a`: Baz.event_a