sphinx入门指南【2】 toctree指令详解

reST本身并不支持同时与多个文档进行交互，或者说将一个文档保存到多个文件中。Sphinx提供了自定义指令toctree来支持实现这个功能。

.. toctree::

这个指令会在当前位置插入文档的目录树。关联文档的路径可以使用相对路径或者绝对路径。 相对路径是指相对于toctree指令所在文件的路径。绝对路径是相对于源文件目录的路径。

maxdepth参数指明了目录的层数，默认是包含所有的层。

假设使用如下doctree指令：

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

上述的指令完成两件事：

• 插入文档的目录，最大层数为2，也就是只包含一级标题与二级标题
• 根据指令中列出的文档顺序，生成导航链接。

文档实体

doctree指令会根据指令中的文档列表，读取它们的文档标题，然后插入到目录中。如果你想自定义文档标题，可以使用类似reST超链接的格式来声明。

.. toctree::

   intro
   All about strings <strings>
   datatypes

第二行将链接到strings文档，但是使用"All about strings"作为标题，而不是strings文档中的标题。

章节序号

如果你需要给章节添加序号，可以给最顶层的toctree添加numbered参数。

.. toctree::
   :numbered:

   foo
   bar

文档序号将从foo开始，子doctree中的文档也会自动添加上序号。

还可以只给某一层的文档添加序号。

其它参数 可以使用caption参数指定目录树的标题，使用name参数，以便ref引用。

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

   foo

如果你只想显示文档的一级标题，可以使用titlesonly参数。

.. toctree::
   :titlesonly:

   foo
   bar

还可以使用unix通配符，通过glob参数指定：

.. toctree::
   :glob:

   intro*
   recipe/*
   *

所有满足匹配条件的文档都将插入到目录中。

上面的指令包含了以intro开头的文档，以及recipe目录中的所有文档，以及剩下的所有文档。

有一个特殊的self文档实体，指代当前toctree指令所在的文档，它可以在生成sitemap时比较有用。

如果你只想使用最顶层的toctree，而忽略掉其它的toctree指令，可以使用includehidden。

.. toctree::
   :includehidden:

   doc_1
   doc_2

最后要注意的是，所有源目录中的文档必须出现在toctree指令中，否则sphinx会告警。

特殊的名字

下面这些名字在sphinx中已经被使用，因此我们的文档名尽量不要使用：

• genindex
• modindex
• search
• 以_开头的名字