Sphinx：modules.rst：警告：文档不包含在任何目录树中

Question

尝试使用 Sphinx 生成文档。

首次使用：

sphinx-apidoc

然后使用：

sphinx-build html

我收到了有关

modules.rst

文件的警告。 文件存在，html也生成了，它看起来绝对像一个目录。

我阅读了我能找到的有关该主题的所有主题，但都没有解决问题（使用

index.rst

指令在

.. include::

文件中正确定位模块声明...）

我不知道该怎么做才能让它发挥作用

这是我的

index.rst

文件的副本，也许你会看到我没有看到的东西。生成的第一个文件位于

sources

文件夹

Welcome to documentation!
=====================================
    
.. toctree::
   :maxdepth: 4
   :caption: Contents:

   modules

   
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我也收到这条消息：

..\doc\sphinx\index.rst:4: WARNING: toctree contains reference to nonexisting document u'modules'

如果我用另一个文档替换模块，我会得到以下信息：

\doc\sphinx\index.rst:4: WARNING: toctree contains reference to nonexisting document u'opsimtest'
looking for now-outdated files... none found
pickling environment... done
checking consistency... \doc\sphinx\_apidocs\modules.rst: WARNING: document isn't included in any toctree

所以看起来即使我在目录树中命名另一个文档，它仍然在寻找modules.rst（并且看不到另一个文档，但是它内置于html文件中）

在本主题中：无法让 sphinx 在 toctree 下链接到另一个文档，错误消息指出

intro.rst

而不是

modules.rst

。 编辑：正如我所说，不幸的是我已经阅读了其他线程，但他们没有解决我的问题。还是坏了。

Answer 1

在休息时，空白是有意义的。指令及其选项必须用空行与其内容分隔。

.. toctree::
    :maxdepth: 4
    :caption: Contents:

    _apidocs/modules

Answer 2

我也遇到过同样的错误。我意识到警告中显示的文件路径（如您的

\doc\sphinx\_apidocs\modules.rst

）不在那里，而是在其他位置。

我已经能够通过修改文件中的 Sphinx-AutoAPI 配置来解决此错误

docs/conf.py

:

不再通过选项

autoapi_dirs = ["../source1", "../source2", "../source3"]

指定所需的目录，而是现在指向包根目录

autoapi_dirs = [".."]

然后我使用选项

autoapi_ignore = ["*pattern1*", "*file2*", "*directory3*"]

排除所有有问题的文件/目录。 请注意，星号

*

需要排除所需的目录，例如“directory3”排除目录

directory3/

中的所有文件。