1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
================================================
:mod:`enum_tools.autoenum` -- Sphinx Extension
================================================
A Sphinx directive for documenting :class:`Enums <enum.Enum>` in Python.
Provides the :rst:dir:`autoenum` directive for documenting :class:`Enums <enum.Enum>`,
and :rst:dir:`autoflag` for documenting :class:`Flags <enum.Flag>`.
These behaves much like :rst:dir:`autoclass` and :rst:dir:`autofunction`.
.. extras-require:: sphinx
:pyproject:
:scope: extension / module
.. extensions:: enum_tools.autoenum
.. contents:: Sections
:depth: 1
:local:
:backlinks: none
Usage
---------
.. rst:directive:: autoenum
autoflag
These directives are used for documenting :class:`Enums <enum.Enum>` and :class:`Flags <enum.Flag>` respectively.
They support the same options as :rst:dir:`autoclass`, but with a few changes to the behaviour:
* Enum members are always shown regardless of whether they are documented or not.
* Enum members are grouped separately from methods.
The docstrings of the Enum members are taken from their ``__doc__`` attributes.
This can be set during initialisation of the enum (see an example `here <https://stackoverflow.com/a/50473952>`_),
with the :class:`~enum_tools.documentation.DocumentedEnum` class, or with the :func:`~enum_tools.documentation.document_enum` decorator.
See the `autodoc module documentation`_ for further details
of the general :rst:dir:`autoclass` behaviour.
.. _autodoc module documentation: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
.. rst:role:: py:enum:mem
py:enum:member
py:flag:mem
py:flag:member
These roles provide cross-references to Enum/Flag members.
.. versionadded:: 0.4.0
Unlike a standard ``:class:`` or ``:enum:`` xref the default behaviour of the
``~`` prefix is to show both the Enum's name and the member's name.
For example:
.. rest-example::
:py:enum:mem:`~enum_tools.demo.StatusFlags.Running`
The original behaviour can be restored by using the ``+`` prefix:
.. rest-example::
:py:enum:mem:`+enum_tools.demo.StatusFlags.Running`
.. latex:vspace:: 10px
Demo
----------
**These two have been created with** ``automodule``.
.. container:: rest-example
.. code-block:: rest
.. automodule:: enum_tools.demo
:members:
.. automodule:: enum_tools.demo
:members:
:exclude-members: NoMemberDoc,StatusFlags,People
:noindex:
:no-autosummary:
.. latex:clearpage::
.. automodule:: enum_tools.demo
:members:
:exclude-members: NoMemberDoc,StatusFlags,NoMethods
:noindex:
:no-autosummary:
.. raw:: html
<p></p>
.. latex:vspace:: 10px
**This one has been created with** ``autoenum``.
.. rest-example::
.. autoenum:: enum_tools.demo.People
:members:
.. latex:clearpage::
**If members don't have their own docstrings no docstring is shown:**
.. rest-example::
.. autoenum:: enum_tools.demo.NoMemberDoc
:members:
.. latex:vspace:: 10px
**Flags can also be documented:**
.. rest-example::
.. autoflag:: enum_tools.demo.StatusFlags
:members:
API Reference
---------------
.. automodule:: enum_tools.autoenum
:no-docstring:
:exclude-members: innernodeclass
|
