`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
Demo
API Reference

Usage

.. autoenum::

.. autoflag::

These directives are used for documenting Enums and Flags 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 the DocumentedEnum class, or with the document_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`

StatusFlags.Running

The original behaviour can be restored by using the + prefix:

:py:enum:mem:`+enum_tools.demo.StatusFlags.Running`

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: int

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: int

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.

classmethod as_list()[source]

Return the Enum’s members as a list.

Return type: List

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: int

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.

classmethod as_list()[source]

Return the Enum’s members as a list.

Return type: List

If members don’t have their own docstrings no docstring is shown:

.. autoenum:: enum_tools.demo.NoMemberDoc
    :members:

enum NoMemberDoc(value)[source]

Bases: enum.IntEnum

An enumeration of people without any member docstrings.

Member Type: int

Valid values are as follows:

Bob = <NoMemberDoc.Bob: 1>

Alice = <NoMemberDoc.Alice: 2>

Carol = <NoMemberDoc.Carol: 3>

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: int

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:

has_errored()[source]

Returns whether the operation has errored.

Return type: bool

API Reference

Classes:

`EnumDocumenter`(*args)	Sphinx autodoc `Documenter` for documenting `Enum`s.
`EnumMemberDocumenter`(directive, name[, indent])	Sphinx autodoc `Documenter` for documenting `Enum` members.
`FlagDocumenter`(*args)	Sphinx autodoc `Documenter` for documenting `Flag`s.
`PyEnumXRefRole`([fix_parens, lowercase, …])	XRefRole for Enum/Flag members.

Functions:

setup(app)

Setup Sphinx Extension.

class EnumDocumenter(*args)[source]

Bases: ClassDocumenter

Sphinx autodoc Documenter for documenting Enums.

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.

Parameters

member (Any)
membername (str)
isattr (bool)
parent (Any)

Return type

bool

document_members(all_members=False)[source]

Generate reST for member documentation.

Parameters: all_members (bool) – If True, document all members, otherwise document those given by self.options.members. Default False.

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. Default None.
real_modname (Optional[str]) – Module name to use to find attribute documentation. Default None.
check_module (bool) – If True, only generate if the object is defined in the module name it is imported from. Default False.
all_members (bool) – If True, document all members. Default False.

class EnumMemberDocumenter(directive, name, indent='')[source]

Bases: AttributeDocumenter

Sphinx autodoc Documenter for documenting Enum 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` and `self.objpath` and set it as `self.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. Default None.
real_modname (Optional[str]) – Module name to use to find attribute documentation. Default None.
check_module (bool) – If True, only generate if the object is defined in the module name it is imported from. Default False.
all_members (bool) – If True, document all members. Default False.

Changed in version 0.8.0: Multiline docstrings are now correctly represented in the generated output.

import_object(raiseerror=False)[source]

Import the object given by self.modname and self.objpath and set it as self.object.

Parameters: raiseerror (bool) – Default False.
Return type: bool
Returns: True if successful, False if an error occurred.

class FlagDocumenter(*args)[source]

Bases: EnumDocumenter

Sphinx autodoc Documenter for documenting Flags.

Methods:

can_document_member(member, membername, …)

Called to see if a member can be documented by this documenter.

classmethod can_document_member(member, membername, isattr, parent)[source]

Called to see if a member can be documented by this documenter.

Parameters

member (Any)
membername (str)
isattr (bool)
parent (Any)

Return type

bool

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).

process_link(env, refnode, has_explicit_title, title, target)[source]

Called after parsing title and target text, and creating the reference node (given in refnode).

This method can alter the reference node and must return a new (or the same) (title, target) tuple.

Parameters

env (BuildEnvironment)
refnode (Element)
has_explicit_title (bool)
title (str)
target (str)

Return type

Tuple[str, str]

setup(app)[source]

Setup Sphinx Extension.

Parameters: app (Sphinx)
Return type: Dict[str, Any]

enum_tools.autoenum – Sphinx Extension

Usage

Demo

API Reference

`enum_tools.autoenum` – Sphinx Extension