sphinxcontrib-enum
This is a Sphinx directive that allows you to document your enums as html tables. Also works for PDFs.
sphinxcontrib-enum
Sphinx directive for documenting dataclass enums in tabular format, with support for enum-properties.
Render dataclass enums as tables with a row for each member and a column for every field. Tables can optionally offer CSV and JSON download buttons. Enums with dataclass values, named tuple values and plain enums work too, and enum-properties enums are also supported!
Installation
pip install sphinxcontrib-enum
To document enum-properties enums, install the properties extra to get a supported version of enum-properties:
pip install "sphinxcontrib-enum[properties]"
Add the extension to your conf.py:
extensions = [
...
"sphinxcontrib_enum",
]
Quick Start
Dataclass Enums
Each dataclass field becomes a column. Field docstrings can describe the columns in an optional legend:
from dataclasses import dataclass
from enum import Enum
@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:: mypackage.Planet
:legend:
:download:
Member Docstrings
Member docstrings are rendered in a doc column. They are parsed as reStructuredText:
from enum import IntEnum
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:: mypackage.Severity
:download:
enum-properties
enum-properties properties become columns, described by their annotation docstrings:
import typing as t
from enum_properties import EnumProperties, Symmetric
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:: mypackage.Shade
:legend:
:download:
Columns, members, headers, widths, captions, download formats and cell formatting can all be customized:
.. enum-table:: mypackage.Planet
:columns: name, radius
:members: EARTH, MERCURY
:headers: name=Planet, radius=Radius (m)
:caption: The inner planets.
Documentation
Full documentation is available at sphinxcontrib-enum.readthedocs.io.
Development
git clone https://github.com/bckohan/sphinxcontrib-enum.git
cd sphinxcontrib-enum
just setup
just install
just test
Contributing
Contributions are welcome! Please see CONTRIBUTING.md.
