75

我收到警告：

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 包含的文件，是否总是出现此警告？

4

4 回答 4

67

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

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

这是一个文件范围的元数据选项。从Sphinx 文档中了解更多信息。

于 2016-11-21T17:24:55.117 回答
44

无论文件是否包含，Sphinx 都会对此抱怨。

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

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

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

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

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

于 2013-03-15T17:48:40.487 回答
6

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

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md
于 2020-03-02T14:56:15.730 回答
2

缩进工作：

  toctree::   
   :maxdepth: 2
       hello <h.rst>
       abc <your.rst>
于 2015-09-21T07:05:04.207 回答