Skip to content

Generate attribute documentation #104

Closed
@manishtomar

Description

@manishtomar

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

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions