专栏首页nummysphinx入门指南【2】 toctree指令详解

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

相关文章

  • 奇怪的编码问题

    今天使用R爬取数据的时候发现一个奇怪的问题,我将每个属性的数据先保存在vector中,然后再合并到data.frame中时,发现打印names时数据正常显示中文...

    用户2936342
  • python堆排序heapq

    堆是一种树形数据结构,其中子节点与父节点之间是一种有序关系。最大堆中父节点大于或等于两个子节点,最小堆父节点小于或等于两个子节点。Python的heapq模块实...

    用户2936342
  • Uninformed search Python实现【译】

    图的搜索可以分为uninformed搜索和informed搜索,两者的区别是前者是的搜索是盲目的,它不知道目标节点在哪,而后者是启发式的搜索。

    用户2936342
  • 基于mdwiki使用Markdown实现的wiki

    子勰
  • SAP Hybris - how to find corresponding cronjob for a given import

    根据SAP帮助文档,每次在HAC里的import都会trigger一个cronjob,我的理解对吗?

    Jerry Wang
  • hbase迁移EMR实践

    一、业务背景: 业务方需要搭建一套hbase集群,数据来源是hive表。 集群数据规模:每天4.5kw个key,420亿条左右数据,平均每个key每天1000个...

    pwpeng
  • 设计师如何管理自己的文档

    三种有效管理文档的方法:文件夹/文件规范命名文档版本控制云盘同步备份通过以上三种方式的配合使用,能有效的帮助我们实现以下目标:通过规范命名:对项目文件/个人文档...

    uedart设计
  • vim打开多个文件、同时显示多个文件、在文件之间切换 打开多个文件:

    1.vim还没有启动的时候: 在终端里输入 vim file1 file2 ... filen便可以打开所有想要打开的文件 2.vim已经启动 输入 ...

    sunsky
  • 72小时紧急驰援:CT+AI攻破新冠肺炎「假阴性」困境 | AI战疫

    有一群人却无暇顾及窗外的雪景,疫情的时钟滴答作响,他们手下的工作正在争分夺秒地进行着——测试算法、优化产品、整理装机……只因他们背负着一个「不可能完成」的任务。

    机器之心
  • 中通消息平台集群突破百万主题的技术探索

    随着业务上的增长与迭代,业务使用的消息集群会创建越来越多主题,在业务流量不断增长的情况下,还需要不断增加主题的分区数量,Kafka 由于本身的存储机制特点,随着...

    张乘辉

扫码关注云+社区

领取腾讯云代金券

,,