Sphinx和argparse - 自动记录命令行脚本？

Question

我正在构建一个Python包，并使用Sphinx创建文档。除了我的包代码外，我还包括许多命令行Python脚本，这些脚本使用argparse。我想知道是否有一种方法可以让Sphinx自动记录这些脚本？最终目标是一个漂亮的脚本列表，带有相关的帮助打印、参数和选项。需要明确的是，我正在寻找一种现成的方法来实现这一点，而不是一种自己实现的方法。

这不是我通常在S.O.上提出的那么具体的问题，如果有更合适的S.E.网站发布这个问题，请让我知道。

- jeremiahbuddha

---

无关，但可能有帮助。请在PyPI上检查plac包。 - Mikko Ohtamaa

不认为这对我的问题有帮助，但很有趣，感谢提醒。 - jeremiahbuddha

Answer 1

使用sphinx-argparse扩展：

http://sphinx-argparse.readthedocs.org/en/latest/

- ribozz

---

很好。有没有一种方法可以将“usage”块处理得不同一些？对我来说，将其作为文字块并不完全正确。 - orome

顺便说一下，如果输出的选项与 .. option:: 的匹配结果相同，那就太好了：只显示标志（不显示默认值），左对齐，描述缩进更少，并将第一个字母大写并在末尾添加句号（因为 --help 的习惯用法是省略这些并使用全小写）。此外，也许可以标记更接近帮助输出的标志条目（例如 -cols [COL [COL ...]] 而不仅仅是 cols），因为所有文本都是在该上下文中编写的。 - orome

Answer 2

你可以使用 sphinxcontrib.programoutput 来包含命令行帮助信息在你的文档中。

这不仅限于 argparse，还可用于记录任何脚本输出的命令行帮助信息。

- bmu

Answer 3

你可以使用 sphinxcontrib.autoprogram。执行 pip install sphinxcontrib-autoprogram，然后放置即可。

extensions += ['sphinxcontrib.autoprogram']

在你的conf.py文件中，要通过传递argparse解析器对象parser来引入cli.py命令进行文档编写。可以使用Python表达式，例如函数get_parser()。

.. autoprogram:: cli:parser
   :prog: cli.py

- asmeurer