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

Question

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

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

然而，当我建立使用

make html

它给出了数千个此类错误：

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

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

除了警告之外，文档似乎工作得很好，但我想把它们去掉，我想我可能对某些东西配置错误。

我也尝试了nipype/工具，几乎相同的效果。

我修改了apigen.py和build_modref_templates.py，为每个“丢失”的文档创建了rst存根，并酌情使用自动类/自动函数/自动符号。然而，构建需要相当长的时间（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

我只是遇到了这个问题，也花了几个小时，以下为我工作：

狮身人面像可能会很挑剔，有时会对你意想不到的事情大惊小怪。例如，您可能会遇到以下情况：

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'

很可能，这里发生的事情是您在中缩进了我的所有信息。。目录树：：有四个空格，而斯芬克斯预期有三个空格。

来源：文档！

Answer 2

如果您使用的是<代码> NUPYDOC 扩展，您可以考虑删除它并使用<代码>狮身人面像。改为ext.poleon。

从1.3版开始，Numpy和Google风格的Docstring实际上就受到这个内置扩展的支持。

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

• 拿破仑-朝着清晰的方向行进

Answer 3

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

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

如果您的文档代码中有一些特殊的文档刮刀，在autosummary已经运行之后正在构建autosummary文档，那么如果您仍然存在此问题，那么您可能需要研究这种想法。虽然，我不确定这会有多大帮助。

链接中的关键是添加：numpydoc\u show\u class\u members=False到conf.py