TOC树

由于reST没有互连多个文档的功能，或者将文档拆分为多个输出文件，Sphinx使用一个自定义指令来添加组成文档的单个文件之间的关系以及目录。toctree指令是其核心元素。

注意

简单地将一个文件“包含”到另一个文件中可以使用include指令。

.. toctree::

该指令使用指令体中给出的文档的各个独立的TOC（包括“子TOC树”）在当前位置插入“TOC树”。相对文档名称（不以斜杠开头）相对于指令出现的文档，绝对名称相对于源目录。可以给出maxdepth数值选项以指示树的深度；默认情况下，包括所有级别。[1]

考虑这个例子（取自Python文档的库参考索引）：

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

它完成两件事：

• 插入所有这些文档的目录，最大深度为2，即一个嵌套标题。这些文档中的toctree指令也考虑到。
• Sphinx知道文档intro、strings等的相对顺序，并且它知道它们是所示文档（库参考索引）的子文档。根据这个信息，它生成“下一章”、“上一章”和“父章”链接。

条目

toctree中的文档标题将自动从引用文档的标题中读取。如果这不是你想要的，你可以使用与reST超链接（和Sphinx的交叉引用语法）类似的语法来指定显式标题和目标。比如：

.. toctree::

   intro
   All about strings <strings>
   datatypes

上面的第二行将链接到strings文档，但将使用标题“All about strings”，而不是strings文档的标题。

你还可以通过提供HTTP URL而不是文档名称来添加外部链接。

小节编号

如果你想在HTML输出中有节号，给顶级toctree指定一个numbered选项。例如：

.. toctree::
   :numbered:

   foo
   bar

然后，编号从foo的标题开始。子toctree将自动编号（不需要给它们numbered标志）。

通过将深度作为数值参数赋给numbered，可以编号到特定深度。

其他选项

你可以使用caption选项提供toctree的一个标题，使用name选项提供隐式的目标名称，它可以使用ref引用：

.. toctree::
   :caption: Table of Contents
   :name: mastertoc

   foo

如果你只想要显示树中文档的标题，而不要显示同一级别的其他头部信息，你可以使用titlesonly选项：

.. toctree::
   :titlesonly:

   foo
   bar

你可以通过给出glob标志选项在toctree指令中使用“globbing”。然后将所有条目与可用文档列表进行匹配，并将匹配项按字母顺序插入列表中。例如：

.. toctree::
   :glob:

   intro*
   recipe/*
   *

这首先包括所有以intro开头的文档，然后是recipe文件夹中的所有文档，然后是所有剩余的文档（当然包含该指令的文档除外）。[2]

特殊条目名称self表示包含toctree指令的文档。如果你想从toctree生成一个“站点地图”，这是有用的。

你可以使用reversed标志选项来颠倒列表中条目的顺序。在使用glob标志选项来颠倒文件的顺序时，这可能很有用。例：

.. toctree::
   :glob:
   :reversed:

   recipe/*

你也可以给指令一个“hidden”选项，像这样：

.. toctree::
   :hidden:

   doc_1
   doc_2

这将仍然通知Sphinx文档层次结构，但不在指令的位置插入链接到文档 —— 这是有意义的，如果你打算自己以不同的样式或在HTML边栏插入这些链接。

如果你想只有一个顶级toctree并隐藏所有其他低级toctrees你可以添加“includehidden”选项到顶级toctree条目：

.. toctree::
   :includehidden:

   doc_1
   doc_2

所有其他的toctree条目可以通过“hidden”选项消除。

最后，源目录（或子目录）中的所有文档必须出现在某个toctree指令中；如果Sphinx发现一个未包括的文件，则会发出警告，因为这意味着该文件将无法通过标准导航访问。

使用exclude_patterns可以显式地从文档或目录中完全排除。使用“orphan”元数据来构建文档，但通知Sphinx它不可通过toctree访问。

“主文档”（由master_doc选择）是TOC树层次结构的“根”。它可以用作文档的主页，如果你不给出maxdepth选项，也可以用作“完整目录”。

在版本0.3中更改：添加“globbing”选项。

在版本0.6中更改：添加“numbered”和“hidden”选项以及外部链接和对“self”引用的支持。

在版本1.0中更改：添加“titlesonly”选项。

在版本1.1中更改：添加“numbered”的数值参数。

在版本1.2中更改：添加“includehidden”选项。

在版本1.3中更改：添加“caption”和“name”选项。

特殊的名称

Sphinx保留一些文档名称供自己使用；你不应该尝试用这些名称创建文档 - 这将导致问题。

特殊文档的名称（和为其生成的页面）为：

• genindex, modindex, search

  这些分别用于一般索引、Python模块索引和搜索页。

  一般索引由来自模块、所有生成索引的对象描述和index指令的条目填充。

  Python模块索引中每个py:module指令包含一个条目。

  搜索页包含一个表单，使用生成的JSON搜索索引和JavaScript对生成的文档进行搜索词全文搜索；它应该在每个支持现代JavaScript的主要浏览器上工作。

• 每个以_开头的名称

  虽然Sphinx当前只使用了很少这样的名称，但你不应该使用这样的名称创建文档或包含文档的目录。（使用_作为自定义模板目录的前缀是正常的。）

警告

小心文件名中的异常字符。某些格式可能会以意想不到的方式解释这些字符：

• 不要对基于HTML的格式使用冒号:。否则，链接到其他部分可能不工作。
• 不要对ePub格式使用加号+。否则，可能找不到某些资源。

脚注

[1]	LaTeX writer仅引用文档中第一个toctree指令的maxdepth选项。

[2]	关于可用的globbing语法的注意事项：你可以使用标准的shell结构*, ?, [...]和[!...]，其特点是这些都不匹配斜杠。双星**可用于匹配任何字符序列包括斜杠。