警告:文档不包含在包含文件的任何目录树中
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),除非有特定原因要覆盖文档的标题。以上是关于警告:文档不包含在包含文件的任何目录树中的主要内容,如果未能解决你的问题,请参考以下文章