enum_tools.autoenum
– Sphinx Extension
A Sphinx directive for documenting Enums
in Python.
Provides the autoenum
directive for documenting Enums
,
and autoflag
for documenting Flags
.
These behaves much like autoclass
and autofunction
.
Attention
This extension / module has the following additional requirements:
sphinx>=3.4.0 sphinx-jinja2-compat>=0.1.1 sphinx-toolbox>=2.16.0
These can be installed as follows:
python -m pip install enum-tools[sphinx]
Enable enum_tools.autoenum
by adding the following
to the extensions
variable in your conf.py
:
extensions = [
...
'enum_tools.autoenum',
]
For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .
Sections
Usage
-
.. autoenum::
-
.. autoflag::
These directives are used for documenting
Enums
andFlags
respectively.They support the same options as
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), with theDocumentedEnum
class, or with thedocument_enum()
decorator.See the autodoc module documentation for further details of the general
autoclass
behaviour.
-
:py:enum:mem:
-
:py:enum:member:
-
:py:flag:mem:
-
:py:flag:member:
These roles provide cross-references to Enum/Flag members.
New in version 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::py:enum:mem:`~enum_tools.demo.StatusFlags.Running`
The original behaviour can be restored by using the
+
prefix::py:enum:mem:`+enum_tools.demo.StatusFlags.Running`
Demo
These two have been created with automodule
.
.. automodule:: enum_tools.demo
:members:
-
enum
NoMethods
(value)[source] Bases:
enum.IntEnum
An enumeration of people without any methods.
- Member Type
Valid values are as follows:
-
Bob
= <NoMethods.Bob: 1> A person called Bob
-
Alice
= <NoMethods.Alice: 2> A person called Alice
-
Carol
= <NoMethods.Carol: 3> A person called Carol
-
enum
People
(value)[source] Bases:
enum.IntEnum
An enumeration of people.
- Member Type
Valid values are as follows:
-
Bob
= <People.Bob: 1> A person called Bob
-
Alice
= <People.Alice: 2> A person called Alice
-
Carol
= <People.Carol: 3> A person called Carol.
This is a multiline docstring.
-
Dennis
= <People.Dennis: 4> A person called Dennis
The
Enum
and its members also have the following methods:-
classmethod
iter_values
()[source] Iterate over the values of the Enum.
This one has been created with autoenum
.
.. autoenum:: enum_tools.demo.People
:members:
-
enum
People
(value)[source] Bases:
enum.IntEnum
An enumeration of people.
- Member Type
Valid values are as follows:
-
Bob
= <People.Bob: 1> A person called Bob
-
Alice
= <People.Alice: 2> A person called Alice
-
Carol
= <People.Carol: 3> A person called Carol.
This is a multiline docstring.
-
Dennis
= <People.Dennis: 4> A person called Dennis
The
Enum
and its members also have the following methods:
If members don’t have their own docstrings no docstring is shown:
.. autoenum:: enum_tools.demo.NoMemberDoc
:members:
Flags can also be documented:
.. autoflag:: enum_tools.demo.StatusFlags
:members:
-
flag
StatusFlags
(value)[source] Bases:
enum.IntFlag
An enumeration of status codes.
- Member Type
Valid values are as follows:
-
Running
= <StatusFlags.Running: 1> The system is running.
-
Stopped
= <StatusFlags.Stopped: 2> The system has stopped.
-
Error
= <StatusFlags.Error: 4> An error has occurred.
The
Flag
and its members also have the following methods:
API Reference
Classes:
|
Sphinx autodoc |
|
Sphinx autodoc |
|
Sphinx autodoc |
|
XRefRole for Enum/Flag members. |
Functions:
|
Setup Sphinx Extension. |
-
class
EnumDocumenter
(*args)[source] Bases:
ClassDocumenter
Sphinx autodoc
Documenter
for documentingEnum
s.Methods:
can_document_member
(member, membername, …)Called to see if a member can be documented by this documenter.
document_members
([all_members])Generate reST for member documentation.
generate
([more_content, real_modname, …])Generate reST for the object given by self.name, and possibly for its members.
-
classmethod
can_document_member
(member, membername, isattr, parent)[source] Called to see if a member can be documented by this documenter.
-
generate
(more_content=None, real_modname=None, check_module=False, all_members=False)[source] Generate reST for the object given by self.name, and possibly for its members.
- Parameters
more_content (
Optional
[Any
]) – Additional content to include in the reST output. DefaultNone
.real_modname (
Optional
[str
]) – Module name to use to find attribute documentation. DefaultNone
.check_module (
bool
) – IfTrue
, only generate if the object is defined in the module name it is imported from. DefaultFalse
.all_members (
bool
) – IfTrue
, document all members. DefaultFalse
.
-
classmethod
-
class
EnumMemberDocumenter
(directive, name, indent='')[source] Bases:
AttributeDocumenter
Sphinx autodoc
Documenter
for documentingEnum
members.Methods:
add_directive_header
(sig)Add the directive header for the Enum member.
generate
([more_content, real_modname, …])Generate reST for the object given by
self.name
, and possibly for its members.import_object
([raiseerror])Import the object given by
self.modname
andself.objpath
and set it asself.object
.-
add_directive_header
(sig)[source] Add the directive header for the Enum member.
- Parameters
sig (
str
)
-
generate
(more_content=None, real_modname=None, check_module=False, all_members=False)[source] Generate reST for the object given by
self.name
, and possibly for its members.- Parameters
more_content (
Optional
[Any
]) – Additional content to include in the reST output. DefaultNone
.real_modname (
Optional
[str
]) – Module name to use to find attribute documentation. DefaultNone
.check_module (
bool
) – IfTrue
, only generate if the object is defined in the module name it is imported from. DefaultFalse
.all_members (
bool
) – IfTrue
, document all members. DefaultFalse
.
Changed in version 0.8.0: Multiline docstrings are now correctly represented in the generated output.
-
-
class
FlagDocumenter
(*args)[source] Bases:
EnumDocumenter
Sphinx autodoc
Documenter
for documentingFlag
s.Methods:
can_document_member
(member, membername, …)Called to see if a member can be documented by this documenter.
-
class
PyEnumXRefRole
(fix_parens=False, lowercase=False, nodeclass=None, innernodeclass=None, warn_dangling=False)[source] Bases:
PyXRefRole
XRefRole for Enum/Flag members.
New in version 0.4.0.
Methods:
process_link
(env, refnode, …)Called after parsing title and target text, and creating the reference node (given in
refnode
).