×

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

96
nummy
2016.10.22 17:09* 字数 682

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
  • 以_开头的名字
sphinx
Web note ad 1