python - 如何记录使用 Sphinx 的点击命令？

Question

Click是一个流行的 Python 库，用于开发 CLI 应用程序。 Sphinx是一个流行的库，用于记录 Python 包。 One problem that some have faced正在集成这两个工具，以便他们可以为其基于点击的命令生成 Sphinx 文档。

我最近遇到了这个问题。我用 click.command 和 click.group 修饰了一些函数，向它们添加了文档字符串，然后使用 Sphinx 的 autodoc 为它们生成了 HTML 文档延期。我发现它省略了这些命令的所有文档和参数描述，因为它们在 autodoc 到达它们时已转换为 Command 对象。

如何修改我的代码，使我的命令的文档在 CLI 上运行 --help 时可供最终用户使用，也可供浏览 Sphinx 生成的文档的人使用？

Answer 1

您可以使用 sphinx 扩展 sphinx-click现在为此。它可以为带有选项和参数描述的嵌套命令生成文档。输出将类似于您运行 --help 时的输出。

用法

1. 安装扩展

pip install sphinx-click

1. 在您的 Sphinx conf.py 文件中启用插件:

extensions = ['sphinx_click.ext']

1. 在文档中必要时使用插件

.. click:: module:parser
   :prog: hello-world
   :show-nested:

例子

有一个简单的click应用程序，它定义在hello_world模块中:

import click


@click.group()
def greet():
    """A sample command group."""
    pass


@greet.command()
@click.argument('user', envvar='USER')
def hello(user):
    """Greet a user."""
    click.echo('Hello %s' % user)


@greet.command()
def world():
    """Greet the world."""
    click.echo('Hello world!')

为了记录所有子命令，我们将使用下面的代码和 :show-nested: 选项

.. click:: hello_world:greet
  :prog: hello-world
  :show-nested:

在构建文档之前，通过使用 setuptools 安装包或手动包含它，确保您的模块和任何其他依赖项在 sys.path 中可用。

构建后我们将得到: generated docs

有关各种可用选项的更多详细信息，请参阅 documentation扩展名