Directive

.. enum-table::

.. enum-table:: import.path.to.Enum
   :columns: name, mass, radius, moons
   :exclude: moons
   :members: EARTH, MARS
   :exclude-members: VENUS
   :headers: mass=Mass (kg), radius=Radius (m)
   :caption: The planets.
   :name: planet-table
   :class: my-class
   :widths: auto
   :download: csv, json
   :formatter: import.path.to.formatter
   :docs: true
   :doc-column: doc
   :legend: true

The only required argument is the import path of the enumeration. The module may be separated from the class with a : (pkg.module:Outer.Enum) or dots may be used throughout (pkg.module.Outer.Enum). If the path cannot be imported on its own it is also tried relative to the current module set by py:currentmodule or py:module.

Options that take lists accept comma or whitespace separated values.

:columns: columns to render (list)

The columns to render, in order. The pseudo-columns name and value are the member’s name and value. Any other column is an attribute (or dotted attribute path) of the member, falling back to its value. Defaults to name, any dataclass fields, value (only when the values are not dataclasses or named tuples), any enum-properties properties and the doc column if any member has a docstring. When given, the doc column is only included where it is listed.

:exclude: columns to drop (list)

Columns to remove from the rendered columns.

:members: members to render (list)

The names of the members to render, in order. Defaults to all members in definition order.

:exclude-members: members to drop (list)

The names of members to leave out of the table.

:headers: column=Header pairs (comma separated list)

Override the header text of columns, for example :headers: mass=Mass, radius=Radius. Headers default to the column name. Header text may not contain commas.

:caption: table caption (text)

A caption for the table. Inline markup is supported.

:name: reference label (text)

A label for cross referencing the table with ref or numref.

:class: css classes (list)

Additional CSS classes to add to the table.

:widths: column widths (auto, grid or a list of integers)

default: auto

Column widths. auto lets the writer size the columns, grid makes them equal and a list of integers gives the relative width of each column (it must have one entry per column).

:download: download formats (list)

default: enum_table_download

The download formats to offer for this table. Supports csv and json, or none to disable downloads. Given without a value, every format is offered. Overrides enum_table_download, which is off by default, so use this to add downloads to individual tables.

:docs: include member docstrings (true or false)

default: true

Whether to add a column with the members’ docstrings. The column is only added if at least one rendered member has a docstring. Accepts true/false, yes/no, on/off or 1/0. Given without a value it is true. See Member Docstrings.

:doc-column: name of the docstring column (text)

default: doc

The name of the column that holds member docstrings. This is its header (unless overridden with enum-table:headers), its key in JSON downloads and the name to use in enum-table:columns and enum-table:exclude. The docstrings override any other column with this name.

:legend: describe the columns beneath the table (true or false)

default: false

Render a legend beneath the table that describes each documented column, using the docstrings of dataclass fields, enum-properties property annotations, named tuple fields and properties. Accepts the same values as enum-table:docs. See Column Legend.

:formatter: import path of a cell formatter (text)

default: enum_table_formatter

The import path of a function to format cells for this table. See Formatter.