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 条评论
登录 后参与评论

相关文章

来自专栏云计算教程系列

如何在Ubuntu 16.04上安装phpIPAM

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

2230
来自专栏Golang语言社区

【Golang语言社区】前端编程-手机端调试利器 - 总结与实践

一些调试工具 说起手机端调试,相比大家都不陌生。 由于手机浏览器没有像PC端浏览器一样有开发调试工具,所以一般手机端的调试都要借助于电脑,现在的调试方式通常有以...

4924
来自专栏同步博客

自定义搭建PHP开发环境

  3、将安装包准备好。http://pan.baidu.com/s/1mhxEPkc

1831
来自专栏WindCoder

windows下python中pip与easy_install相关

下载地址:https://pypi.python.org/pypi/ez_setup

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

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

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

9447
来自专栏吴伟祥

IntelliJ IDEA代码编辑器中的HTTP客户端

Scratch文件可用于在开发期间测试HTTP请求。临时文件不存储在项目中,因此IntelliJ IDEA可以修改它并添加有关请求的其他信息。从临时文件执行HT...

4973
来自专栏静下来

增加wordpress可以上传.torrent文件

今天想上传个文件,是.torrent后缀的。。就是种子,为什么要上传,咱就不说了。。。wordpress本身是不支持上传.torrent文件的,不过我们可以用代...

3385
来自专栏代码散人

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

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

1424
来自专栏玩转JavaEE

MongoDB副本集搭建

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

3786
来自专栏源码之家

mysql数据库还原出错ERROR:Unknown command ‘\\’解决手记

2065

扫码关注云+社区

领取腾讯云代金券