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不在任何toctree中，如：

/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 documentation。

中的更多内容

Answer 2

Sphinx会抱怨文件是否包含在内。

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

因此，对于您的情况，您可以尝试类似：

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

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

Answer 3

缩进工作：

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

Answer 4

我遇到了无法编辑要作为git子模块导入的文档的情况。这些文档已经具有自己的结构，包括用Markdown编写的TOC页面，我确实希望通过sphinx对它们进行处理以确保格式的一致性。

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md

警告：文档不包含在所包含文件的任何toctree中

4 个答案: