我正在尝试使用 Sphinx 自动为大型 python 代码库创建 api 文档。
我尝试过使用 build_modules.py 和 sphinx-apidoc。无论使用哪一种，我都可以在输出目录中成功创建包和顶级模块的第一个文档。
但是，当我使用
构建时make html
它给出了数千个此类错误：
<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'
对于代码库中的每个类和方法。 通过一些实验，我想我发现自动摘要/自动类指令正在创建目录树，期望每个类和方法都有第一个文件。
除了警告之外，文档似乎运行良好，但我想删除它们，并且我认为我可能配置错误。
我也尝试过 nipype/tools 达到了同样的效果。
我修改了 apigen.py 和 build_modref_templates.py 为每个“缺失”文档创建第一个存根，并根据需要使用 autoclass/autofunction/automethods。然而，构建需要相当长的时间（10 分钟），并且最终由于最后一个构建步骤的内存错误而崩溃。
这是创建所有警告的示例模块第一个文件：
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 站点包文件的解决方案。
很抱歉这么晚才回答（如果可以考虑的话），但我发现这个链接讨论了您可能会发生的事情：
https://github.com/phn/pytpm/issues/3#issuecomment-12133978
如果您的文档代码中有一些特殊的文档抓取器，在自动摘要已经运行后构建自动摘要文档，如果您仍然遇到此问题，则可能需要考虑一下。虽然，我不确定这会有多大帮助。
链接中的关键是将：
numpydoc_show_class_members = Falseconf.py我也刚刚遇到这个问题，并花了几个小时来解决这个问题，以下对我有用：
狮身人面像可能会很挑剔，有时会做出一些你意想不到的事情。 例如，你很可能会遇到这样的事情：
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'很可能，这里发生的情况是，当 Sphinx 期望三个空格时，您在
中缩进了“关于我”四个空格。.. toctree::
来源：文档！
如果您正在使用
numpydocsphinx.ext.napoleon从 1.3 版本开始，这个内置扩展实际上支持 Numpy 和 Google 风格的文档字符串。
删除
numpydocsphinx.ext.napoleonconf.py在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:'
使用 numpydoc 时，将
Methodsnumpydoc 文档中的示例：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