sphinxcontrib-enumΒΆ
A Sphinx directive for documenting dataclass enums in tabular format. Each member is a row and each dataclass field is a column. Tables can optionally be downloaded as CSV or JSON.
Documents enums that mix in a dataclass or whose values are dataclasses (or named tuples).
Columns may be any attribute, property or dotted path on the member or its value.
Filter and reorder columns and members, rename headers, add captions and cross references.
Member docstrings are rendered in a
doccolumn.Optional column legends from field and property docstrings.
Customize how cells render with a formatter function.
Optional CSV and JSON download buttons (html builders only).
Supports enum-properties enums as a special case, and plain enums work too.
For example:
Each dataclass field becomes a column, and field docstrings can describe them in a legend:
@dataclass(frozen=True)
class PlanetData:
mass: float
"""Mass in kilograms."""
radius: float
"""Radius in meters."""
#: Number of known moons.
moons: int
class Planet(PlanetData, Enum):
MERCURY = 3.303e23, 2.4397e6, 0
VENUS = 4.869e24, 6.0518e6, 0
EARTH = 5.976e24, 6.37814e6, 1
MARS = 6.421e23, 3.3972e6, 2
.. enum-table:: examples.Planet
:legend:
:download: csv, json
Member docstrings are rendered in a doc column:
class Severity(IntEnum):
DEBUG = 10
"""Diagnostic detail, usually disabled in production."""
INFO = 20
"""Routine operational messages."""
#: Something unexpected happened that the application **recovered** from.
WARNING = 30
ERROR = 40
"""A failure that needs attention.
See :ref:`usage` for how to render these tables."""
CRITICAL = 50
.. enum-table:: examples.Severity
enum-properties properties become columns, described by their annotation docstrings:
class Shade(EnumProperties):
label: t.Annotated[str, Symmetric()]
"""A human readable label."""
hex: t.Annotated[str, Symmetric(case_fold=True)]
"""The hex color code, without a leading ``#``."""
RED = 1, "Red", "ff0000"
GREEN = 2, "Green", "00ff00"
BLUE = 3, "Blue", "0000ff"
.. enum-table:: examples.Shade
:legend:
:download:
Contents:
Indices and tables