Sphinx自动摘要中“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，它们期望每个类和方法都有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 site-package文件的解决方案。

- user1287170

---

你确定你有一个 toctree 条目指向生成的文档吗？例如，指向你上面发布的 src 包文档？ - Kevin Horn

相关未解决问题：https://github.com/numpy/numpydoc/issues/69 - taper

Answer 1

非常抱歉回复晚了（如果可以算作回复），但我找到了这个链接，讨论了可能发生在您身上的情况：

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

如果您在文档代码中有一些特殊的文档抓取器，可以在autosummary运行后构建autosummary文档，这个想法可能值得考虑，如果您仍然遇到此问题。不过，我不确定这会有多大帮助。

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

- djhoese

---

如果你这样做，那会删除方法表 :( - Andreas Mueller

有没有人发现一种不会删除方法表的解决方案？我无法切换到sphinx.ext.napoleon，因为它似乎不支持与numpydoc_use_plots相同的功能。 - Aaron Voelker

有人发现了一种不会删除方法表的解决方案吗？ 是的，将matplotlib/sphinxext/plot_directive.py复制到您的文档本地目录中，并将其用作额外的sphinx指令。 - Alex Kaszynski

Answer 2

我也遇到了这个问题，花了几个小时才解决。以下方法对我有效：

Sphinx can be fussy, and sometimes about things you weren’t expecting. For example, you well encounter something like:

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'

Quite likely, what has happened here is that you indented all-about-me in your .. toctree:: with four spaces, when Sphinx is expecting three.

Source: docs!

- 0x78f1935

---

终于找到问题了；我脸上流下了幸福的泪水。 - Vincent

Answer 3

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

自版本1.3以来，此内置扩展实际上支持Numpy和Google风格的文档字符串。

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

---

Sources

• 拿破仑——迈向易读的文档字符串
• Sphinx Doc - 支持NumPy和Google风格的文档字符串

- Kurt Bourbaki

Answer 4

在Sphinx 5.3中，您的缩进需要保持一致（空格数量似乎并不重要）。

三个空格的缩进也可以使用：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   admin/index

两个空格缩进也可以使用：

.. toctree::
  :maxdepth: 2
  :caption: Contents:

  admin/index

然而，如果缩进不一致，例如:maxdepth:缩进三个空格，但admin/index只缩进两个空格，如下所示...

.. toctree::
   :maxdepth: 2
   :caption: Contents:

  admin/index

如果你的程序存在问题，那么很可能会收到警告：

WARNING: toctree contains reference to nonexisting document ' :maxdepth: 2'
WARNING: toctree contains reference to nonexisting document ' :caption: Contents:' 

- w. Patrick Gale

Answer 5

使用numpydoc时，将Methods标题添加到类的文档字符串中可能会解决这些警告。

来自numpydoc文档的示例：https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

class Photo(ndarray):
    """
    Array with associated photographic information.

    ...

    Attributes
    ----------
    exposure : float
        Exposure in seconds.

    Methods
    -------
    colorspace(c='rgb')
        Represent the photo in the given colorspace.
    gamma(n=1.0)
        Change the photo's gamma exposure.

    """

在我看来，这有点过于冗余，但它确实可以让你保留方法表。

另外，作为一个替代方案，你可以使用类似这样的方法（但是方法表将被移除）。

:modname:`src`
---------------------------
.. automodule:: src.__init__
   :show-inheritance:
   :private-members:
   :undoc-members:
   :special-members: __call__
   :inherited-members:

有点奇怪的是，:members:会引起问题，但:private-members:却不会。

供参考，自2016年以来，numpydoc上有一个关于此问题的未解决问题。https://github.com/numpy/numpydoc/issues/69

- ReenigneArcher