Python sphinx 警告：文档不是'；t包含在包含文件的任何目录树中

我得到了警告：

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

奇怪的是，我可以在输出中看到内容。这正常吗？对于显式包含而不是通过目录树包含的文件，是否始终显示此警告

---

谢谢

无论文件是否包含，Sphinx都会对此进行投诉

但是，您可以使用config值专门排除文件

因此，对于您的情况，您可以尝试使用以下内容更改Sphinx的

conf.py

文件：

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

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

编辑：请参阅：获取创建此答案后添加的另一个选项。

缩进工作：

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

目录树： ：maxdepth:2 你好 abc

---

如果您只想

。包括：：

另一个文档中的文档，而不让它出现在任何

目录树中

将
：孤立：
添加到文档顶部以消除警告。

这是一个文件范围的元数据选项。阅读更多信息。
我遇到了一个无法编辑我希望作为git子模块引入的文档的情况。这些文档已经有了自己的结构，包括用Markdown编写的TOC页面，我确实希望sphinx能够处理它们，以确保格式的一致性

我发现我可以做的是指定一个隐藏的toctree，使toctree知道文档，而不是将toctree弄得乱七八糟，或者在sphinx构建输出中添加一堆错误

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md

*：doc:`附加书籍`
.. 目录树：：
：隐藏：
外部/documentA.md
外部/文档b.md
AFAIK，Sphinx会将未明确包含在目录树中的每个.rst文件视为“杂散”，并发出警告消息。另请参见此答案：。您显示的缩进并不需要，但是，在
：maxdepth:2
和下一行之间有一个空行。它也可以/应该是简单的
h
（文件名减去rst），除非有特定的原因要覆盖文档的标题。另外，请参阅
：hidden:
目录树的选项。谢谢，在少数情况下这似乎是一个很好的答案。我们的用例使用的是一个生成的文件，我们不想在顶部手动插入
：orphan:
标记。我喜欢这个答案，因为它还可以帮助我跟踪当前文档中引用的外部文档。