Sphinx 自动摘要“toctree 包含对不存在的文档的引用"警告 [英] Sphinx autosummary "toctree contains reference to nonexisting document" warnings

问题描述

我正在尝试使用 Sphinx 为大型 Python 代码库自动创建 api 文档.

I am trying to automatically create api docs for a large python codebase using Sphinx.

我尝试过使用 build_modules.py 和 sphinx-apidoc.使用任何一个，我都可以在我的输出目录中为包和顶级模块成功创建 rst 文档.

I have tried using build_modules.py and sphinx-apidoc. With either one, I can get rst docs successfully created in my output directory for the packages and top-level modules.

但是，当我构建使用

make html

它给出了数千个这种类型的错误:

it gives thousands of errors of this type:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

对于代码库中的每个类和方法.通过一些实验，我想我已经发现 autosummary/autoclass 指令正在创建目录树，这些目录树期望每个类和方法都有 rst 文件.

for every single class and method in the codebase. With some experimentation I think I have discovered that the autosummary/autoclass directives are creating toctrees that expect there to be rst files for every class and method.

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

Other than the warnings, the documentation seems to work well, but I would like to get rid of them and I think I may have misconfigured something.

我也尝试过 nipype/tools 的效果大致相同.

I have also tried nipype/tools to much the same effect.

我修改了 apigen.py 和 build_modref_templates.py 为每个这些缺失"的文档创建第一个存根，并根据需要使用 autoclass/autofunction/automethods.然而，构建需要相当长的时间(10 分钟)，最终由于最后构建步骤的内存错误而崩溃.

I modified apigen.py and build_modref_templates.py to create rst stubs for each of these "missing" documents, with autoclass/autofunction/automethods as appropriate. However, the build takes quite a long time (10 minutes) and eventually crashes due to memory errors on the last build step.

这是一个创建所有警告的示例模块 rst 文件:

Here is an example module rst file that creates all the warnings:

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

Thanks for any advice on how to make these warnings resolve! I would like to stay away from any solution that involves modifying the sphinx site-package files.

推荐答案

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

Sorry for such a late answer (if it can be considered that) but I found this link that discusses what may be happening to you:

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

如果您的文档代码中有一些特殊的 Doc 抓取工具在自动摘要已经运行后构建自动摘要文档，如果您仍然遇到此问题，可能需要研究一下.虽然，我不确定这会有多大帮助.

The idea that if you have some special Doc scraper in your documentation code that is building autosummary documentation after autosummary has already run may be something to look into if you are still having this issue. Although, I'm not sure how much help this will be.

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

The key from the link is to add: numpydoc_show_class_members = False to conf.py

这篇关于Sphinx 自动摘要“toctree 包含对不存在的文档的引用"警告的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！