Sphinx 自动摘要“目录树包含对不存在文档的引用”警告

Question

我正在尝试使用 Sphinx 为大型 python 代码库自动创建 api 文档。

我尝试过使用 build_modules.py 和 sphinx-apidoc。使用任何一个，我都可以在我的输出目录中为包和顶级模块成功创建第一个文档。

但是，当我使用构建时

make html

它给出了数千个这种类型的错误：

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

对于代码库中的每个类和方法。 通过一些实验，我想我发现 autosummary/autoclass 指令正在创建期望每个类和方法都有 rst 文件的目录树。

除了警告之外，文档似乎运行良好，但我想摆脱它们，我想我可能配置错误。

我也尝试过nipype/tools，效果大致相同。

我修改了apigen.py 和build_modref_templates.py 来为这些“缺失”的文档中的每一个创建第一个存根，并根据需要使用自动类/自动功能/自动方法。但是，构建需要相当长的时间（10 分钟），最终由于最后一个构建步骤的内存错误而崩溃。

这是一个创建所有警告的示例模块 rst 文件：

src Package
===========

:mod:`src` Package
------------------

.. automodule:: src.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example1` Module
------------------------------------

.. automodule:: src.Example1
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example2` Module
------------------

.. automodule:: src.Example2
    :members:
    :undoc-members:
    :show-inheritance:

感谢您就如何解决这些警告提供任何建议！我想远离任何涉及修改 sphinx 站点包文件的解决方案。

Answer 1

很抱歉这么晚的答案（如果可以考虑的话），但我发现这个链接讨论了你可能发生的事情：

https://github.com/phn/pytpm/issues/3#issuecomment-12133978

如果您的文档代码中有一些特殊的 Doc scraper 在 autosummary 已经运行后构建 autosummary 文档，那么如果您仍然遇到此问题，则可能需要考虑这一点。不过，我不确定这会有多大帮助。

链接中的关键是添加：numpydoc_show_class_members = False to conf.py

Answer 2

如果您使用的是numpydoc 扩展，您可以考虑将其删除并改用sphinx.ext.napoleon。

从 1.3 版开始，这个内置扩展实际上支持 Numpy 和 Google 样式的文档字符串。

因此，删除numpydoc 并在conf.py 中使用sphinx.ext.napoleon 可能会解决您的问题。

---

来源

• Napoleon - Marching toward legible docstrings
• Sphinx Doc - Support for NumPy and Google style docstrings

Answer 3

我也遇到了这个问题，花了几个小时，以下对我有用：

狮身人面像可能会很挑剔，有时甚至会出现一些出乎你意料的事情。 例如，您会遇到类似的情况：

WARNING: toctree contains reference to nonexisting document u'all-about-me'
...
checking consistency...
<your repository>/my-first-docs/docs/all-about-me.rst::
WARNING: document isn't included in any toctree'

很可能，这里发生的情况是，您在 .. toctree:: 中用四个空格缩进了 all-about-me，而 Sphinx 期望的是三个空格。

来源：docs!