专栏首页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
  • 以_开头的名字
本文参与 腾讯云自媒体分享计划 ,欢迎热爱写作的你一起参与!
本文分享自作者个人站点/博客:https://www.jianshu.com/u/69ba0aedbe3c复制
如有侵权,请联系 cloudcommunity@tencent.com 删除。
登录 后参与评论
0 条评论

相关文章

  • sphinx入门指南【1】快速入门

    包含.rst文件的根目录称之为源文件目录,目录中还包含sphinx的配置文件conf.py。

    用户2936342
  • Sphinx+gitee+Read the Docs搭建在线文档系统

    本文介绍一种在线文档系统的搭建,需要借助Sphinx、gitee和Read the Docs。

    xxpcb
  • Sphinx补篇

    我的写作习惯是用到的参考资料直接发出来,在阅读起来可能有一丝割裂感.但是在学习的感觉上是,由浅入深,由浅入深的感觉,以下的所有文章都是这样........

    云深无际
  • 用Sphinx快速制作文档

    简介 Sphinx 是一种文档工具,它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是...

    木制robot
  • ReStructuredText 文档编写全攻略编写文档说明

    谢伟
  • 使用 Python 30分钟 教你快速搭建一个博客

    10个优秀的程序员里,有9个人都有写博客的习惯。这是非常好的习惯,它使得知识得以提炼,转输出为输入,在提升自己的同时,还能利用互联网易传播的特性,将知识分享给每...

    小小詹同学
  • Python利用sphinx构建个人博客

    KaliArch
  • Python学习资源大集合

    苦叶子
  • 使用python编写量子线路打印的简单项目,并使用Sphinx自动化生成API文档

    该文章一方面从量子线路的打印着手,介绍了一个简单的python量子线路工程。同时基于这个简单的小工程,我们顺带的介绍了python的API文档自动化生成工具Sp...

    DechinPhy
  • 科学软件十条简单编程原则

    科学,尤其是生物学,越来越依赖软件工具来实现研究。但是,如果您是生物学家,则可能未接受过软件开发最佳实践方面的培训。由于缺乏培训,科学软件通常只有极少甚至不存在...

    lyb-geek
  • Web前端开发推荐阅读书籍、学习课程下载

    学校里没有前端的课程,那如何学习JavaScript,又如何使自己成为一个合格的前端工程师呢?

    慕白
  • 飞龙的程序员书单 - 组原、OS、网络

    简单介绍一下,这本书包括组成原理和操作系统两大部分知识。第二、三章学完之后,逆向就算是入门了。国内的教材很少有拿汇编和C语言对比教学的书籍,这样的教学方法很实用...

    ApacheCN_飞龙
  • 速成记|安装PaddlePaddle到底分几步?

    和哪个版本的PaddlePaddle可以牵手成功,首先对自己的“英雄”要足够了解,尤其是这三个硬性条件

    用户1386409
  • Apache Spark 2.2.0 中文文档 - 概述 | ApacheCN

    Spark 概述 Apache Spark 是一个快速的, 多用途的集群计算系统。 它提供了 Java, Scala, Python 和 R 的高级 API...

    片刻
  • 一些免费的学习资源 原

    HTML5 Canvas编程:http://blog.csdn.net/column/details/canvas-programming.html GTK编...

    wuweixiang
  • 灵魂追问 | 教程那么多,你……看完了吗?

    机器之心
  • Node.js 技术栈学习指南(含思维导图)

    说明:大致方向不会变,中间细节部分之后可能会修改,欢迎关注公众号「Nodejs技术栈」回复 “思维导图” 查看最新版学习指南

    用户1462769
  • 【程序源代码】非常棒的java学习面试指南

    最近好多同学想学习java,我在网上找了找终于找到这个指南。这一个非常不错的java学习指南。内容包含的比较全面,知识点也比较完整。

    程序源代码
  • Android:这是一份全面 & 详细的RxJava学习攻略

    首先,我将带大家入门 RxJava,主要介绍其作用、基础使用等,解决的是:初学者不理解Rxjava原理 & 不懂得如何使用的问题。

    Carson.Ho

扫码关注腾讯云开发者

领取腾讯云代金券