Sphinx autosummary "toctree包含对不存在的文档的引用“警告

Question

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

我尝试过使用build_modules.py和sphinx-apidoc。无论使用哪种方法，我都可以在我的输出目录中成功地为包和顶级模块创建rst文档。

但是，当我使用

make html

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

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

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

除了警告之外，文档似乎工作得很好，但我想摆脱它们，我想我可能配置错了什么。

我也尝试过nipype/tools来达到同样的效果。

我修改了apigen.py和build_modref_templates.py，为每个“丢失”的文档创建rst存根，并使用适当的autoclass/autofunction/automethods方法。然而，构建花费了相当长的时间(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

如果你的文档代码中有一些特殊的文档抓取器，在autosummary已经运行之后正在构建autosummary文档，如果你仍然有这个问题，那么这个想法可能是值得考虑的。虽然，我不确定这会有多大的帮助。

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

Answer 2

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

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

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

资料来源

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

Answer 3

我也遇到了这个问题，花了几个小时在这个问题上，下面的方法对我很有效：

Sphinx可能会挑剔，有时会对你意想不到的事情大惊小怪。例如，您可能会遇到这样的情况：

警告: toctree包含对不存在的文档u‘’all about-me‘的引用...正在检查一致性.../my-first-docs/docs/all-about-me.rst:：WARNING:文档未包含在任何toctree中‘

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

来源：docs！