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

Posted

技术标签:

【中文标题】警告:文档不包含在包含文件的任何目录树中【英文标题】: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 视为“流浪”,并发出警告消息。另请参阅此答案:***.com/a/13109215/407651。 【参考方案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),除非有特定原因要覆盖文档的标题。

以上是关于警告:文档不包含在包含文件的任何目录树中的主要内容,如果未能解决你的问题,请参考以下文章

查找目录树中最新的 500 个文件的命令,并且符合 POSIX

如何使用 SWIG 包装许多 .h 文件并包含任何依赖项?

您可以关闭特定位置包含的任何标头的(特定)编译器警告吗?

B+树索引

open-ldap schema

Eclipse中的部署目录在哪里?