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站点包文件的解决方案。

Answer 1

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

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

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

链接中的密钥是将numpydoc_show_class_members = False添加到conf.py

Answer 2

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

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

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

来源

Answer 3

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

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.

来源：docs！

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

3 个答案:

来源