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

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文档中的更多内容.

Answer 2

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

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

所以对于你的情况你可能会尝试类似的东西:

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

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

Answer 3

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

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md