警告：文档未包含在包含文件的任何目录树中

Question

我收到警告：

WARNING: document isn't included in any toctree

对于文档中存在的文件，因为它们已被明确包含。所以我有索引文件：

.. toctree::
    :maxdepth: 2

   pages/0010-foo
   pages/0020-bar

在文件 0020-bar.rst 中，我特别包含了许多其他文件，如下所示：

.. contents:: :local:

.. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst

但是当我构建项目时，我仍然收到一条警告，提示 0070-baz.rst 不在任何目录树中，如下所示：

/home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn't included in any toctree

奇怪的是我可以看到输出中的内容。这是正常的吗？对于显式包含而不是通过 toctree 包含的文件，是否总是出现此警告？

Answer 1

如果您只想将一个文档

..include::

放入另一个文档中，而不希望它出现在任何

toctree

中。

将

:orphan:

添加到文档顶部以消除警告。

这是一个“文件范围元数据”选项。从 Sphinx 文档阅读更多内容。

Answer 2

但是，您可以使用

exclude_patterns

配置值专门排除文件。 因此，对于您的情况，您可以尝试使用以下内容更改 Sphinx 的

conf.py

文件：

exclude_patterns = ['pages/reference-architecture', 'some/other/file.txt']

您可以排除单个文件、目录，或使用文件通配模式以这种方式匹配文件组。

编辑：

请参阅：Joakim 的答案，了解创建此答案后添加的另一个选项。

Answer 3

我发现我可以做的是指定一个隐藏的 toctree 以使 toctree 知道文档，但不会弄乱 toctree 或在我的 sphinx 构建输出中添加一堆错误。

* :doc:`Additional Book <external/index>`

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md

Answer 4

  toctree::   
   :maxdepth: 2
       hello <h.rst>
       abc <your.rst>

Answer 5