Sphinx Autodoc vs. Coverage:我在这里遗漏了什么吗?

时间:2015-10-30 12:29:43

标签: python python-sphinx autodoc

我正在尝试使用Sphinx来记录包含各种子包和子模块的Python包。我按照库存Sphinx快速入门脚本生成了带有autodoc指令的各种文件,而这些指令反过来又与html生成器一起生成了基于现有文档字符串的文档的大致预期的第一遍。代码。凉。

现在输入sphinx.ext.coverage。由于项目在“快速启动”脚本之后存在,因此运行sphinx-build -b coverage <other args>根本不会产生任何有意义的输出,只需:

Undocumented Python objects
===========================

......在它下面什么都没有。我故意删除了一些文档字符串以确保,当然,没有任何警告。

我徘徊了一会儿,最终尝试使用非autodoc指令,瞧,coverage突然出现了。遗憾的是,autodoc功能是Sphinx首先吸引人的主要原因。但是好的,为每个模块添加.. py:module::指令有帮助;它似乎使coverage扩展知道我的模块,并从那里开始在我的python.txt中获取有关那些没有文档字符串的模块中的成员的条目。这很好,但似乎意味着要coverage报告模块,必须在doc文件中明确地手动声明该模块,这有助于降低coverage工具的价值(即如果我向软件包添加一个新模块,它会显示它不会包含在覆盖率报告中,直到我专门为它添加一个指令。)所以,我看到的是autodoc似乎能够自动遍历子模块/包,但coverage没有。

问题:我错过了什么吗?无法自动发现项目中出现的新代码对于“覆盖”工具来说似乎是一个非常明显的错误。在我看来,标准的覆盖工具应该选择退出,而不是选择加入。

当我进一步推动时,我发现更多证据表明coverageautodoc不是朋友。例如,即使使用.. py:module::指令手动声明模块(如上所述),我发现coverage没有发现像autodoc的{​​{1}}指令这样的事情。正如预期的那样,该指令在构建HTML时忽略了生成的输出中的成员匹配,但exclude-members仍然在其覆盖报告中将这些成员报告为未记录的。从我的阅读

问题coveragecoverage之间的不兼容是否在我无法找到的文档中找到了?或者,我又错过了什么?

0 个答案:

没有答案