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

【问题标题】：WARNING: document isn't included in any toctree for included file警告：文档不包含在包含文件的任何目录树中
【发布时间】：2013-02-21 08:40:42
【问题描述】：

我收到警告：

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 包含的文件，是否始终显示此警告？

【问题讨论】：

AFAIK，没有明确包含在目录树中的每个 .rst 文件都被 Sphinx 视为“流浪”，并发出警告消息。另请参阅此答案：stackoverflow.com/a/13109215/407651。

标签： python-sphinx restructuredtext toctree

【解决方案1】：

如果您只想在另一个文档中..include:: 一个文档，而不让它出现在任何toctree 中。

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

这是一个文件范围的元数据选项。阅读更多来自Sphinx documentation。

【讨论】：

另外，请参阅toctree 的:hidden: 选项。

【解决方案2】：

无论文件是否包含，Sphinx 都会抱怨这一点。

但是，您可以使用 exclude_patterns 配置值专门排除文件。

因此，对于您的情况，您可以尝试使用以下内容更改 Sphinx 的 conf.py 文件：

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

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

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

【讨论】：

【解决方案3】：

我有一种情况，我无法编辑我想作为 git 子模块引入的文档。这些文档已经有了自己的结构，包括用 Markdown 编写的 TOC 页面，我确实希望它们由 sphinx 处理以保持格式的一致性。

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md

【讨论】：

谢谢，在某些情况下，这似乎是一个很好的答案。我们的用例是使用生成的文件，我们不想在顶部手动注入 :orphan: 标记。
我喜欢这个答案，因为它还可以帮助我跟踪当前文档中引用了哪些外部文档。

【解决方案4】：

缩进有效：

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

【讨论】：

您显示的缩进绝不是必需的，但是，:maxdepth: 2 和下一行之间的空行是。它也可以/应该是简单的 h（文件名减去 rst），除非有特定原因要覆盖文档的标题。