sphinx-list-items

A Sphinx extension to automatically list figures, tables, and Sphinx version directives (versionadded, versionchanged, deprecated, versionremoved) in your documentation. Output as a bulleted list or a customizable table, with filtering and advanced options.

Features

• List all figures or tables in your documentation
• List Sphinx version directives (with prefix-stripping for cleaner output)
• Output as a bulleted list or a table (with custom columns)
• Filter version items by version number
• Works with cross-references and section links

Installation

pip install sphinx-list-items

Or for development:

pip install -e .

Setup

Add to your conf.py:

extensions = ['sphinx_list_items']

Usage

List all figures (as a list)

.. list-items:: figures
   :list:

List all figures (as a table)

.. list-items:: figures
   :table:

List all tables (as a list)

.. list-items:: tables
   :list:

List all tables (as a table)

.. list-items:: tables
   :table:

List Sphinx version directives (as a list)

.. list-items:: versionadded
   :list:

.. list-items:: versionchanged
   :list:

.. list-items:: deprecated
   :list:

.. list-items:: versionremoved
   :list:

List Sphinx version directives (as a table)

.. list-items:: versionadded
   :table:

Filter version items by version

.. list-items:: versionadded
   :table:
   :version: 0.0.2

Custom columns for tables

.. list-items:: versionchanged
   :table: docname, version, text, type

Advanced

• All output supports cross-references to the source location.
• Version directive output strips the prefix (e.g., "Added in version 1.0.0:") for clean summaries.
• You can use :list: or :table: for any supported type.
• For tables, you can specify custom columns (e.g., :table: id, caption).

Example

See the examples and specimens in this repository for real-world usage.