48

我正在尝试使用 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来为这些“缺失”的每个文档创建第一个存根，并根据需要使用 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 站点包文件的解决方案。

4

3 回答 3

44

抱歉这么晚的答案（如果可以考虑的话），但我发现这个链接讨论了你可能发生的事情：

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

如果您的文档代码中有一些特殊的 Doc scraper 在 autosummary 已经运行之后构建 autosummary 文档，那么如果您仍然遇到此问题，则可能需要考虑这个想法。虽然，我不确定这会有多大帮助。

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

于 2013-03-04T20:46:22.790 回答
11

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

从 1.3 版开始，这个内置扩展实际上支持 Numpy 和 Google 样式的文档字符串。

因此，在您的遗嘱中删除numpydoc和使用可能会解决您的问题。sphinx.ext.napoleonconf.py

来源

于 2017-04-05T17:30:05.020 回答
9

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

狮身人面像可能会很挑剔，有时会涉及到您没有预料到的事情。例如，您会遇到类似的情况：

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 期待三个空格。

来源：文档！

于 2019-05-20T14:46:44.620 回答