Closed
Description
It would nice if sphinx based documentation can be automatically generated from validators when possible. For example, following class
@attr.s
class SelfHeal(object):
"""
A class that triggers convergence on all the groups over a time range.
:ivar clock: Reactor providing timing APIs
:vartype: :obj:`IReactorTime`
:ivar dispatcher: Effect dispatcher to perform all effects
(ZK, CASS, log, etc)
:vartype dispatcher: Either :obj:`ComposedDispatcher` or
:obj:`TypeDispatcher`
:ivar callable config_func: Callable used when calling
:func:`tenant_is_enabled`
:ivar float time_range: Seconds over which convergence triggerring will be
spread evenly
:ivar log: :obj:`BoundLog` object used to log messages
:ivar list _calls: List of :obj:`IDelayedCall` objects. Each object
represents scheduled call to trigger convergence on a group
"""
clock = attr.ib(validator=attr.validators.provides(IReactorTime),
)
dispatcher = attr.ib(
validator=attr.validators.instance_of((ComposedDispatcher,
TypeDispatcher)))
config_func = attr.ib()
time_range = attr.ib(validator=attr.validators.instance_of(float),
convert=float)
log = attr.ib(
validator=attr.validators.instance_of(BoundLog),
convert=lambda l: l.bind(otter_service="selfheal"),
cmp=False)
_calls = attr.ib(default=attr.Factory(list))
could be simplified by
@attr.s(doc=True)
class SelfHeal(object):
"""
A class that triggers convergence on all the groups over a time range.
"""
clock = attr.ib(validator=attr.validators.provides(IReactorTime),
doc="Reactor providing timing APIs")
dispatcher = attr.ib(
validator=attr.validators.instance_of((ComposedDispatcher,
TypeDispatcher)),
doc="Effect dispatcher to perform all effects")
config_func = attr.ib(doc="Callable used when calling :func:`tenant_is_enabled`")
time_range = attr.ib(
validator=attr.validators.instance_of(float), convert=float,
doc="Seconds over which convergence triggerring will be spread evenly")
log = attr.ib(
validator=attr.validators.instance_of(BoundLog),
convert=lambda l: l.bind(otter_service="selfheal"),
cmp=False, doc="Object used to log messages")
_calls = attr.ib(
default=attr.Factory(list),
doc=("Each object represents scheduled call to trigger convergence "
"on a group"))
Since the docs are next to attribute definition it makes the docs more comprehensible.
Metadata
Metadata
Assignees
Labels
No labels