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

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指令正在创建toctrees,期望每个类和方法都有第一个文件.

除了警告之外,文档似乎运行良好,但我想摆脱它们,我想我可能错误配置了一些东西.

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

我修改了apigen.py和build_modref_templates.py,为每个"缺失"文档创建了第一个存根,并使用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文件的解决方案.

Answer 1

很抱歉这么晚的答案(如果可以考虑的话),但我发现这个链接讨论了可能发生在你身上的事情:

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

如果您仍然遇到此问题,那么如果您的文档代码中有一些特殊的Doc scraper正在构建autosummary文档,那么可能需要考虑自动总结.虽然,我不确定这会有多大帮助.

链接的关键是添加:numpydoc_show_class_members = Falsetoconf.py

Answer 2

如果您使用的是numpydoc扩展程序,则可以考虑将其删除并使用sphinx.ext.napoleon.

从版本1.3开始,Numpy和Google风格的文档字符串实际上受到此内置扩展的支持.

因此,删除numpydoc和使用sphinx.ext.napoleon您的conf.py遗嘱可能会解决您的问题.

来源

• 拿破仑 - 走向清晰易读的文轨
• Sphinx Doc - 支持NumPy和Google风格的文档字符串

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 需要三个空格。

资料来源：文档！