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.