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

时间:2013-03-06 14:02:27

标签: python-sphinx restructuredtext

我收到了警告:

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包含的文件,是否始终显示此警告?

谢谢!

4 个答案:

答案 0 :(得分:31)

如果您只想..include::另一个文档中的文档,而不会将其显示在任何toctree中。

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

这是文件范围的元数据选项。阅读Sphinx documentation

中的更多内容

答案 1 :(得分:22)

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

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

因此,对于您的情况,您可以尝试类似:

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

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

答案 2 :(得分:1)

缩进工作:

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

答案 3 :(得分:1)

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

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

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

.. toctree::
   :hidden:

   external/documentA.md
   external/documentB.md