autoenum Sphinx Extension

.. autoenum::
.. autoflag::

Used to document Enums and Flags respectively.

The directives 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 https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html for further details.

:py:enum:mem:
:py:enum:member:
:py:flag:mem:
:py:flag:member:

Provides cross-references to Enum/Flag members.

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, e.g.

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

StatusFlags.Running

The original behaviour can be restored by using the + prefix, e.g.

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

Running


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/index.html#third-party-extensions .

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

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

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>

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