# Sphinx Integration

Stevedore includes an extension for integrating with Sphinx to automatically produce documentation about the supported plugins. To activate the plugin add `stevedore.sphinxext` to the list of extensions in your `conf.py`.

.. list-plugins:: namespace

  List the plugins in a namespace.

  Options:

  `detailed`

    Flag to switch between simple and detailed output (see below).

  `overline-style`

    Character to use to draw line above header, defaults to none.

  `underline-style`

    Character to use to draw line below header, defaults to `=`.

## Simple List

By default, the `list-plugins` directive produces a simple list of plugins in a given namespace including the name and the first line of the docstring. For example:

    .. list-plugins:: stevedore.example.formatter

produces

- field – Format values as a reStructuredText field list.

- plain – A very basic formatter.

- simple – A very basic formatter.

## Detailed Lists

Adding the `detailed` flag to the directive causes the output to include a separate subsection for each plugin, with the full docstring rendered. The section heading level can be controlled using the `underline-style` and `overline-style` options to fit the results into the structure of your existing document.

    .. list-plugins:: stevedore.example.formatter
       :detailed:

produces

### field

Format values as a reStructuredText field list.

For example:

    : name1 : value
    : name2 : value
    : name3 : a long value
        will be wrapped with
        a hanging indent

### plain

A very basic formatter.

### simple

A very basic formatter.

Note

Depending on how Sphinx is configured, bad reStructuredText syntax in the docstrings of the plugins may cause the documentation build to fail completely when detailed mode is enabled.

this page last updated: 2026-03-20 10:56:09

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug