Sphinx 集成

Stevedore 包含一个扩展，用于与 Sphinx 集成，以自动生成有关受支持插件的文档。要激活此插件，请将 stevedore.sphinxext 添加到 conf.py 文件中的扩展列表。

.. list-plugins:: namespace

列出命名空间中的插件。

选项

detailed

标志，用于在简单输出和详细输出之间切换（见下文）。

overline-style

用于绘制标题上方线条的字符，默认为无。

underline-style

用于绘制标题下方线条的字符，默认为 =。

简单列表

默认情况下，list-plugins 指令会生成给定命名空间中插件的简单列表，包括名称和 docstring 的第一行。例如

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

生成

  • field – 将值格式化为 reStructuredText 字段列表。

  • plain – 一个非常基本的格式化程序。

  • simple – 一个非常基本的格式化程序。

详细列表

将 detailed 标志添加到指令会导致输出为每个插件包含一个单独的子部分，并渲染完整的 docstring。可以使用 underline-style 和 overline-style 选项来控制标题级别，以使结果适应现有文档的结构。

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

生成

field

将值格式化为 reStructuredText 字段列表。

例如

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

plain

一个非常基本的格式化程序。

simple

一个非常基本的格式化程序。

注意

根据 Sphinx 的配置，插件 docstring 中的不良 reStructuredText 语法可能会导致文档构建在启用详细模式时完全失败。