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
  • 以_开头的名字

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏SpringBoot 核心技术

第十四章:QueryDSL与SpringDataJPA共同服务于SpringBoot

3354
来自专栏北京马哥教育

73条日常shell命令汇总,总有一条你需要!

1.检查远程端口是否对bash开放: echo >/dev/tcp/8.8.8.8/53 && echo "open" 2.让进程转入后台: Ctrl + z...

36311
来自专栏Python自动化测试

python自动化环境搭建

selenium是测试web应用程序的框架,selenium为没有测试脚本的人提供了(seleniumide)提供了录制/回放的工具,同时它也提供了特定...

1333
来自专栏世界第一语言是java

mysql官网下载最新版升级版本多版本安装教程

2105
来自专栏Linux运维学习之路

ansible批量管理软件部署及剧本

服务器版本信息: Centos6.9 [root@db02 ~]# uname -a Linux db02 2.6.32-696.el6.x86_64 #1 S...

8347
来自专栏开发技术

将tomcat添加为linux系统服务

  在博客 --》virtualBox安装centos,并搭建tomcat中,讲到了centos下搭建tomcat环境,发现启动tomcat不是那么方便,要是忘...

1382
来自专栏代码散人

利用XCode Targets创建多scheme的iOS项目

在我们的开发iOS的时候,通常会遇到一个项目打包成多个环境的问题,也会遇到一套代码打包成多个项目的问题,最常用的做法是写一个配置文件,在打包的时候修改一下配置文...

1164
来自专栏玩转JavaEE

MongoDB副本集搭建

我们之前的案例都是在单个节点上实现的,在生产环境中这种做法是有风险的,如果服务宕机、崩溃或者硬盘坏了都会对公司业务造成损失,因此我们需要数据备份。在MongoD...

3696
来自专栏云计算教程系列

如何在Ubuntu 16.04上安装phpIPAM

phpIPAM是一个专用的IP地址管理工具,超越低技术选项通过提供自动ping扫描,状态报告,让您可以看到哪些主机已启动,哪些已停机,通过电子邮件发送有关你正在...

1760
来自专栏张伟博客

如何使用 Git 和 GitHub 来管理自己的代码

    点击右上角加号箭头,在弹出的菜单中选择 "New repository" 选项进行仓库配置。

1282

扫码关注云+社区