python - 狮身人面像自动摘要 "toctree contains reference to nonexisting document"警告

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 指令正在创建期望每个类和方法都有 rst 文件的目录树。

除了警告之外，文档似乎运行良好，但我想摆脱它们，我想我可能配置错误。

我也试过nipype/tools效果差不多。

我修改了apigen.py和 build_modref_templates.py为这些“缺失”文档中的每一个创建第一个 stub ，并根据需要使用 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 已经运行后构建 autosummary 文档，那么如果您仍然遇到此问题，则可能需要考虑这一点。不过，我不确定这会有多大帮助。

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