我正在尝试使用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
没有。
问题:我错过了什么吗?无法自动发现项目中出现的新代码对于“覆盖”工具来说似乎是一个非常明显的错误。在我看来,标准的覆盖工具应该选择退出,而不是选择加入。
当我进一步推动时,我发现更多证据表明coverage
和autodoc
不是朋友。例如,即使使用.. py:module::
指令手动声明模块(如上所述),我发现coverage
没有发现像autodoc
的{{1}}指令这样的事情。正如预期的那样,该指令在构建HTML时忽略了生成的输出中的成员匹配,但exclude-members
仍然在其覆盖报告中将这些成员报告为未记录的。从我的阅读
问题:coverage
和coverage
之间的不兼容是否在我无法找到的文档中找到了?或者,我又错过了什么?