Python sphinxcontrib是否在抓取解析器后自动编程解析参数？

我正在创建一个Python包，其中包含一个使用子命令模式的命令行界面：

kevlar count

，

kevlar partition

，等等。CLI工作得非常出色，现在我正试图将CLI添加到Sphinx文档中。在寻找解决方案的过程中，我遇到了一个似乎完全符合我要求的解决方案，甚至显式地处理子命令。但是当我执行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\u args（）

（意外）。“invalid”

html

参数来自sphinx命令行生成调用，但在某些地方被误认为是我的库的CLI中的子命令之一

我的语法似乎与sphinxcontrib自动编程文档相匹配

.. autoprogram:: cli:parser
   :prog: kevlar

是什么导致了这种行为？

---

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

• 解析器在中定义
• 每个命令的子Parser在中的专用文件中定义（例如）

---

首先，确保您的程序使用，这是

自动编程的一项要求：

扫描
argparse.ArgumentParser
对象，然后将其展开为一组
。。程序：：
和
。。选项：：
指令

其次，您使用的语法可能不正确。看起来您是从第一个示例中复制pastad，而不是阅读其内容。具体而言：

.. autoprogram:: module:parser

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

因此，在您的例子中，假设您的
解析器（）
创建并返回一个
argparse.ArgumentParser
，那么您的语法将类似于或接近于此：

.. autoprogram:: kevlar.cli:parser()
    :prog: kevlar

困难的部分是找出准确、正确的
模块：parser
替换

要与另一个示例进行比较，请参阅
pcreate
的金字塔文档的、源和。您应该在单独的模块中加载
argparse
实例，该模块创建相同的
argparse
实例，但不执行解析器本身。或者，您的模块可以检测到它已加载到自动程序中，并在构建
argparse
实例后退出

例如，PoC库使用了一个非常庞大的
argparse
命令行解析器和许多子解析器。前端脚本如下所示：

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

def __init__(self, debug, verbose, quiet, dryRun, sphinx=False):
    # Call the initializer of ILogable
    # --------------------------------------------------------------------------
    if quiet:      severity = Severity.Quiet
    elif debug:    severity = Severity.Debug
    elif verbose:  severity = Severity.Verbose
    else:          severity = Severity.Normal

    logger = Logger(severity, printToStdOut=True)
    ILogable.__init__(self, logger=logger)

    # Call the constructor of the ArgParseMixin
    # --------------------------------------------------------------------------
    description = dedent("""\
        This is the PoC-Library Service Tool.
        """)
    epilog = "Pile-of-Cores"

    class HelpFormatter(RawDescriptionHelpFormatter):
        def __init__(self, *args, **kwargs):
            kwargs['max_help_position'] = 25
            super().__init__(*args, **kwargs)

    ArgParseMixin.__init__(self, description=description, epilog=epilog, formatter_class=HelpFormatter, add_help=False)
    if sphinx: return

资料来源：

如果由Sphinx加载，则加载和中止的代码：

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

def __init__(self, debug, verbose, quiet, dryRun, sphinx=False):
    # Call the initializer of ILogable
    # --------------------------------------------------------------------------
    if quiet:      severity = Severity.Quiet
    elif debug:    severity = Severity.Debug
    elif verbose:  severity = Severity.Verbose
    else:          severity = Severity.Normal

    logger = Logger(severity, printToStdOut=True)
    ILogable.__init__(self, logger=logger)

    # Call the constructor of the ArgParseMixin
    # --------------------------------------------------------------------------
    description = dedent("""\
        This is the PoC-Library Service Tool.
        """)
    epilog = "Pile-of-Cores"

    class HelpFormatter(RawDescriptionHelpFormatter):
        def __init__(self, *args, **kwargs):
            kwargs['max_help_position'] = 25
            super().__init__(*args, **kwargs)

    ArgParseMixin.__init__(self, description=description, epilog=epilog, formatter_class=HelpFormatter, add_help=False)
    if sphinx: return

资料来源：

类PileOfCores实现了一个属性来返回主解析器对象
MainParser
，该对象存储在
autoprogram
所期望的变量
parser
中，我不确定它是否有用，但这个问题提醒了我（关于optparse而不是argparse）。“困难的部分是找出准确、正确的
模块：parser
替换。”嗯，错误消息清楚地表明调用了正确的函数。问题是
ArgumentParser
对象似乎是被执行的，而不是被检查的。