sphinxcontribautoprogram是否在获取解析器后解析参数？

Question

我正在创建一个Python包，其命令行接口使用子命令模式：kevlar count，kevlar partition，依此类推。CLI的工作原理非常棒，现在我正试图将CLI添加到Sphinx文档中。在寻找解决方案的过程中，我遇到了sphinxcontrib-autoprogram，它似乎正是我想要的，甚至显式地处理子命令。但是当我执行sphinx构建时，我得到以下错误。在

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.6.3
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [ 20%] cli
usage: sphinx-build [-h] [-v] [-l F] cmd ...
sphinx-build: error: argument cmd: invalid choice: 'html' (choose from 'reaugment', 'dump', 'novel', 'collect', 'mutate', 'assemble', 'filter', 'partition', 'count', 'localize')
make[1]: *** [html] Error 2
make: *** [doc] Error 2

sphinx扩展似乎不仅创建了argparse对象（预期的），而且还在对其调用parse_args()（意外）。“invalid”html参数来自sphinx命令行构建调用，但在某个地方被误认为是库的CLI中的一个子命令。在

我的语法似乎与sphinxcontrib自动程序文档匹配。在

^{pr2}$

是什么导致了这种行为？

---

我不确定这些细节是否与问题有关，但如果它们是：

• 解析器在^{}中定义
• 每个命令的子parser在kevlar/cli/中的专用文件中定义（例如kevlar/cli/count.py）

Answer 1

您应该在一个单独的模块中加载argparse实例，该模块创建相同的argparse实例，但不执行解析器本身。或者您的模块可以检测到它是在autoprogram中加载的，并在构造argparse实例后退出。在

例如，PoC库使用非常庞大的argparse命令行解析器和许多子解析器。前端脚本如下：py/PoC.py

docs目录包含一个虚拟前端，它触发argparse的实例化，但在构造后中止。在

虚拟加载PoC的代码：

from sys import path as sys_path
sys_path.append("../py")

from PoC import PileOfCores

# entry point
parser = PileOfCores(False, False, False, True, sphinx=True).MainParser

来源：docs/PoCSphinx.py

要加载并中止的代码（如果由Sphinx加载）：

^{pr2}$

来源：py/PoC.py

PileOfCores类实现了一个属性，以返回主解析器对象MainParser，该对象存储在autoprogram期望的变量parser中。在

Answer 2

首先，确保程序使用argparse，这是autoprogram的要求：

scans argparse.ArgumentParser object, and then expands it into a set of .. program:: and .. option:: directives.

其次，您使用的语法可能不正确。看起来您复制了第一个示例中的pastad，而不是读取其usage。具体来说：

.. autoprogram:: module:parser

module是模块的点式导入名，parser是引用argparse.ArgumentParser对象或创建并返回对象的Python表达式的变量。在

因此，在您的例子中，假设您的parser()创建并返回一个argparse.ArgumentParser，那么您的语法应该是这样或接近它的：

^{pr2}$

困难的部分是找出准确、正确的module:parser替换。在

要与另一个示例进行比较，请参见pcreate的金字塔文档的source program、源reST file和{a5}。在