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 apydispatch.Property
object.
- Property prop_b: int = 0#
Description of prop_b
prop_b
is apydispatch.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 apydispatch.ListProperty
object.
- ListProperty prop_b: List[int]#
Description of prop_b
prop_b
is apydispatch.ListProperty
object.
- DictProperty prop_c: Dict[str, Any] = {'foo': 'bar'}#
Description of prop_c
prop_c
is apydispatch.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 apydispatch.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
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`
:attr:`Foo.prop_a`
:obj:`Foo.prop_a`
And Baz.event_a
can be referenced using
:event:`Baz.event_a`
:attr:`Baz.event_a`
:obj:`Baz.event_a`