Sphinx 集成

用法

cliff 支持通过 Sphinx 指令 与 Sphinx 集成。

准备工作

在使用 autoprogram-cliff 指令之前，您必须将 ‘cliff.sphinxext’ 扩展模块添加到 conf.py 中的 extensions 列表中

extensions = ['cliff.sphinxext']

指令

.. autoprogram-cliff:: <命名空间> 或 <app 类>

自动记录 cliff.command.Command 或 cliff.app.App 的实例，包括描述、用法摘要以及所有选项的概述。

重要提示

此指令有两种模式：command 模式和 app 模式。该指令接受一个必需的参数，模式根据指定的参数确定。

command 模式记录指定 cliff.command.Command 实例的各种信息。command 模式将命令可以在其中找到的命名空间作为参数。这通常在 setup.cfg 或 setup.py 的 entry_points 部分中定义。您可以使用 :command: 选项指定应显示哪些命令。

.. autoprogram-cliff:: openstack.compute.v2
   :command: server add fixed ip

app 模式记录指定 cliff.app.App 实例的各种信息。app 模式将相应类的 python 路径作为参数。在 app 模式下，通常指定 :application: 选项，以便在渲染输出中显示命令名称。

.. autoprogram-cliff:: cliffdemo.main.DemoApp
   :application: cliffdemo

有关更多信息，请参阅下面的 示例。

此外，可以提供以下指令选项

:command

命令的名称，如果从命令行调用而不使用可执行文件名，则会这样显示。这将在 setup.cfg 或 setup.py 中定义，尽管带有下划线。这是可选的，并且支持 fnmatch 样式的 通配符。有关更多信息，请参阅下面的 示例。

此选项仅在 command 模式下有效。

:arguments

实例化 cliff 应用程序时要传递的参数。某些 cliff 应用程序在实例化时需要参数。可以使用此选项指定这些参数。

此选项仅在 app 模式下有效。

:application

顶级应用程序名称，将在所有命令之前加上前缀。此选项覆盖下面描述的全局选项 autoprogram_cliff_application。在大多数情况下，全局配置就足够了，但如果您的 sphinx 文档处理多个 cliff 应用程序，则此选项很有用。

参见

配置选项 autoprogram_cliff_application。

:ignored

从该选项的文档中排除的选项的逗号分隔列表。这对于价值较低的选项很有用。

参见

配置选项 autoprogram_cliff_ignored。

支持以下全局配置值。这些应放置在 conf.py 中

autoprogram_cliff_application

顶级应用程序名称，将在所有命令之前加上前缀。这通常在 setup.cfg 或 setup.py 的 entry_points 部分的 console_scripts 属性中定义。有关更多信息，请参阅下面的 示例。

例如

autoprogram_cliff_application = 'my-sample-application'

默认值为 ''

参见

指令选项 :command:。

参见

指令选项 :application:。

autoprogram_cliff_ignored

从文档中排除的选项的全局列表。这可用于防止常见选项（例如用于分页的选项）在所有选项中重复出现。

例如

autoprogram_cliff_ignored = ['--help', '--page', '--order']

默认值为 ['--help']

参见

指令选项 :ignored:。

autoprogram_cliff_app_dist_name

提供正在记录的命令/应用程序的 python 发行版名称（用于 pip 的名称，而不是用于导入的包名称）。插件组件的生成文档包括指示插件名称的消息。设置此选项会告诉 cliff 提供组件的发行版名称，因此其文档不包含此消息。

参见

模块 sphinxcontrib.autoprogram

一个等效的库，用于与纯 argparse 应用程序一起使用。

模块 sphinx-click

一个等效的库，用于与 click 应用程序一起使用。

重要提示

autoprogram-cliff 指令发出标记为 shell 代码的 code-block 代码段。这需要 pygments >= 0.6。

示例

简单示例 (demoapp)

cliff 提供了一个示例应用程序 探索 Demo 应用程序，以演示 cliff 的一些功能。该应用程序 使用 cliff.sphinxext Sphinx 扩展进行了 记录。

高级示例 (python-openstackclient)

也可以记录更大的应用程序，例如 python-openstackclient。以下是一个示例 setup.cfg 文件，它是 python-openstackclient 项目提供的 setup.cfg 的一个最小版本

[entry_points]
console_scripts =
    openstack = openstackclient.shell:main

openstack.compute.v2 =
    host_list = openstackclient.compute.v2.host:ListHost
    host_set = openstackclient.compute.v2.host:SetHost
    host_show = openstackclient.compute.v2.host:ShowHost

这将注册三个命令 - host list、host set 和 host show - 用于名为 openstack 的顶级可执行文件。要记录第一个命令，请添加以下内容

.. autoprogram-cliff:: openstack.compute.v2
   :command: host list

您也可以一次性注册所有这些命令，如下所示

.. autoprogram-cliff:: openstack.compute.v2
   :command: host *

最后，如果这些是该命名空间中唯一的命令，则可以完全省略 :command: 参数

.. autoprogram-cliff:: openstack.compute.v2

在所有情况下，您应该将以下内容添加到 conf.py 中，以确保所有用法示例都显示完整的命令名称

autoprogram_cliff_application = 'openstack'