乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > 使用Sphinx构建软件说明书(5):reStructuredText语法

使用Sphinx构建软件说明书(5):reStructuredText语法

当前时间： 2026-01-14 16:16:53 分类：软件教程 评论(0)

使用Sphinx构建软件说明书(5):reStructuredText语法

使用Sphinx构建软件说明书（5）：reStructuredText语法

微信公众号：生信小知识关注可了解更多的生物信息学教程及知识。问题或建议，请公众号留言;

目录

前言1. reStructuredText简介1.1 OmniMarkupPreviewer1.2 sphinx-autobuild2. 文档结构语法2.1 标题语法2.2 段落3. 文本的一般语法4. 列表4.1 无序列表4.2 有序列表4.3 定义列表4.4 字段列表4.5 参数列表5. 超链接5.1 外部链接5.1.1 带别名的超链接5.1.2 匿名超链接5.2 锚点链接5.3 间接链接5.4 隐式超链接6. 文本块6.1 文字块6.2 行块6.3 块引用6.4 文档测试块7. 特殊提示8. 代码高亮8.1 快速定义代码块8.2 code-block代码高亮8.3 嵌入整个文件8.4 文件对比9. 添加图片9.1 使用 image 指令9.2 使用 figure 指令10. 表格10.1 网格表格10.2 简单表格11. 数学表达式11.1 行内数学表达式11.2 行间数学表达式12. 角色与指令12.1 角色12.2 指令13. 脚注13.1 手工序号13.2 自动序号13.3 自动符号14. 目录15. 不同文档之间相互引用后记

前言

我决定使用Sphinx对开发的软件包写一个说明书，这里记录我学习Sphinx的记录。

所有知识来源：

  • https://www.osgeo.cn/sphinx-note/intro.html
  • Sphinx 1.3.1 中文手册 (推荐查看)

已发布教程：

前面的教程，已经让我们掌握了构建工具的使用方法。接下来我们则主要学习下编写文档语言—— reStructuredText (rst)

1. reStructuredText简介

reStructuredText是一个易读，易写，所见即所得的明文标记语法和解析系统，对于 “in-line” 程序文档（如 Python docstrings）非常有用，用于快速创建简单的网页和本地文档。作为Python官方文档工具，标准统一，对输出格式有更细粒度的控制。

不过reStructuredText的语法比Markdown复杂，某些标记比Markdown更冗长。

正当我准备以学习Markdown的方式学习reStructuredText时，我发现一个严重的问题——没有reStructuredText版本的Typora软件。

这就说明，我没有办法对我输入的每个代码直观看到渲染后的结果。

经过查找，我一共发现2个相对好用的小工具：

  • sublime小插件：OmniMarkupPreviewer
  • sphinx配套小工具：sphinx-autobuild

1.1 OmniMarkupPreviewer

这是一个针对sublime工具的小插件。安装后使用起来非常方便，只是它仅仅针对于基础reStructuredText语法，对于稍微高级点的语法则无法解析（例如代码块中的一些设置）。但是这个工具的好处就在于即时渲染。

使用时，我们需要先讲文档格式定义为 reStructuredText，不然会没有反应。

然后 ctrl+alt+o 键则会弹出一个页面窗口，在这个页面窗口中会即时出现渲染后的效果。

注意：在使用时一定要将sublime中的文件格式修改为reStructuredText！！！否则会发现无论怎么使用快捷键 ctrl+alt+o 都没有任何反应！

1.2 sphinx-autobuild

这个在使用上相对复杂点，但是好处是它支持高级的语法，可以渲染出各种复杂的功能。

同样的，我们需要先安装：

$ pip install sphinx-autobuild

在使用上，则和 sphinx-build 命令基本一致：

$ sphinx-autobuild -husage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]positional arguments:  SOURCE_DIR            文档源文件地址  OUTPUT_DIR            输出地址  filenames             （可选）指定具体的源文件名general options:  --builder, -b BUILDER                        构建文件类型，默认为【html】  --jobs, -j N          多线程，指定数目  --write-all, -a       构建所有文件， 默认仅重构有改动的文件path options:  --doctree-dir, -d PATH                        存放doctree以及环境文件的地址【OUTPUT_DIR/.doctrees】  --conf-dir, -c PATH   存放配置文件conf.py的地址【SOURCE_DIR】build configuration options:  --isolated, -C        不使用配置文件，只使用-D 规定的参数  --define, -D setting=value                        设置参数，以“-D setting=value”形式  --html-define, -A name=value                        给HTML templates模板传递变量console output options:  --verbose, -v         增加代码过程中的输出信息  --quiet, -q           不输出提醒，只对错误提示  --silent, -Q          什么都不输出  --color               对输出的字符进行标色  --no-color, -N        对输出的字符不进行标色warning control options:  --warning-file, -w FILE                        将警告及报错导出到指定文件  --fail-on-warning, -W                        将警告转为报错  --exception-on-warning                        如果警告就停止

所以我们可以打开一个命令行，然后输入下面命令：

$ sphinx-autobuild SOURCEDIR OUTPUTDIR

注意：麻烦的地方在于，我们需要每次将文件保存（ctrl+s），然后再刷新网页，才可以看到效果。

2. 文档结构语法

2.1 标题语法

任意可打印的 7 个bit的ASCII码字符都可以作为章节标识符，包括：

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

不过有些可能会看起来比较奇怪，因此推荐使用其中的

= - ` : . ' " ~ ^ _ * + #
  • 在reStructureText中未明确各个章节标识符层级的顺序，它按照标识符在书写文本中的顺序来指定标识符指示的标题层级 。
  • 在标题上下使用两行标识符，和只在标题下使用一行标识符效果是一样的。
  • 标题标识符的数量至少要和标题文本等长，对于中文标题，一般标识符的长度要大于标题的长度。
  • 建议定义如下标题标识符层级（从高到低）为 = - , . *

例如：

=======C1=======-------C1.1-------*******C1.1.1**************C1.1.2*******-------C1.2-------=======C2=======-------C2.1-------*******C2.1.1*******,,,,,,,C2.1.1.1,,,,,,,.......C2.1.1.1.......-------C2.2-------

得到的结果如下：

2.2 段落

转换分隔用于段与段之间的分隔，相当于html中的 <hr> ，就是跨屏的一个横线。

使用4个及以上的标点符号（推荐使用短横 - ）就可以生成，同样需要前后空行（以避免和标题语法混淆）。另外，不能连续出现

示例如下：

前后需要空行,,,,,,,,使用标点符号.........不能连续出现---------

效果如下：

3. 文本的一般语法

这部分和markdown语法类似。

加粗、斜体及代码块：

**强调***斜体1*`斜体2```代码块``

4. 列表

4.1 无序列表

一般使用 “+-*” 来作为无序列表的指示符，利用进来指示列表之间的嵌套关系（2个空格）

- 1  - 1.1    - 1.1.1* 2  * 2.1    * 2.1.1

每个大点后，必须空一行，而相同等级之间，可以不空行，例如：

- 1- 2  - 2.1  - 2.2

4.2 有序列表

枚举指示符有，阿拉伯数字（1, 2, 3, … ）；大写字母（A-Z）；小写字母（a-z）；大写罗马数字（I, II, III, IV, …, MMMMCMXCIX）；小写罗马数字（i, ii, iii, iv, …, mmmmcmxcix）。并且可以使用 “#” 来自动自增。

支持各种前缀和后缀格式，例如：

  • 1.
  • 1)
  • (1)

这里放一个例子：

1. aaa#. bbb#. ccc#. ddd#. eee1) aaa#) bbb#) ccc#) ddd#) eee(a) aaa(#) bbb(#) ccc(#) ddd(#) eee

此外，当正常的文本中包含可被识别为列表的内容时（ A. 1. (b) I 等），为了避免被识别，可以采取如下措施：

  1. 将一行内容，折断为多行书写，这样会被识别为 段落 内容，而不会解析为列表；
  2. 使用反斜杠 “\” 在段首进行转义。

例如：

A. Einstein was a reallysmart dude. （跨行避免）A. Einstein was a really smart dude.（未避免）\A. Einstein was a really smart dude.（使用\转义）

有序列表也支持嵌套，规则和无序列表一致，只是用3个空格进行缩进。例如：

1. Item 1 initial text.   a) Item 1a.   b) Item 1b.#. Item 2 initial text.   a) Item 2a.使用#号自增   b) Item 2b.
1. Item 1 initial text.#. Item 2 initial text.   a) Item 1a.   b) Item 1b.   c) Item 1c.   d) Item 1d.

4.3 定义列表

可以理解为解释列表，即名词解释。

条目占一行，解释文本要有缩进；多层可根据缩进实现。

各个条目由三部分组成：

  • 条目名称：条目名称和条目属性在同一行，使用空格、冒号、空格（” : “）连接，其中条目属性可以为空。
  • 条目属性：必须紧接着条目名称，中间不能空行打断。
  • 条目定义：可以有多个条目定义，需要换行缩进。这里的缩进没有明确规定，可以用任意数目空格，不过同一个条目名称下的条目定义之间，缩进使用的空格数目要保持相同。

说起来复杂，让我们用实际例子进行学习：

term 1 Definition 1.term 2  Definition 2, paragraph 1.  Definition 2, paragraph 2.term 3 : classifier    Definition 3.term 4 : classifier one : classifier two     Definition 4.

4.4 字段列表

用于指令解释，或者数据库字段解释的场景。它在形式上有点像两列的表格。

其格式类似于 :字段: 解释内容

其中，字段中可以包含空格，但是不能包含冒号

:Date: 2020-02-02:Version: 1:Authors1: - fire           - firewang           - firewang:Authors2: fire           firewang           firewang:Indentation: Since the field marker may be quite long, the second  and subsequent lines of the field body do not have to line up with first line.  解释可能很长，第二行不用和第一行对齐，但是后续行必须和第二行对齐。:Parameter i: 字段中可以带空格，但是不能带":"

4.5 参数列表

选项列表是一个左列为参数，右列为参数说明的两列列表（无表头），用于command-line参数解释。

支持三种参数书写形式:

  • 由一个短横（Short dash）连接的 POSIX 式。
  • 由两个短横（Short dash）连接的 长POSIX 式。
  • DOS/VMS参数形式，即由 / 起始的参数形式。

示例如下：

-a             command-line option "a"-b file        options can have arguments and                long descriptions--long         options can also be long--input=file   long options can also have                arguments/V             DOS/VMS-style options too

5. 超链接

Sphinx 中支持多种格式的超链接声明。 注意 Sphinx 本身不支持在新页面打开链接的功能，要实现这个功能可以安装一个扩展 sphinx-new-tab-link， 或者使用原生 HTML 标签创建。

超链接Hyperlink 有三种：

  • 带别名的超链接 ，语法为 .. hyperlink-name: url` ；由 `..`，空格，短下划线 ` ，别名，冒号，空格和链接地址构成。 在原文引用处书写语法为 hyperlink-name_ （特别注意原文中”_”在别名后，而在指示链接出，”_”在别名前）。
  • 匿名anonymous的超链接，即不带别名的超链接，语法为 .. : url` ； 由 `..`，空格，两个短下划线 ”`”，冒号，空格和链接地址构成。
  • 匿名的超链接，另一种语法形式
    ，语法为 __ url 。

我们还是用具体例子来做讲解。

5.1 外部链接

5.1.1 带别名的超链接

外部链接有两种方式，需要引用的话，使用上述带别名的超链接的语法形式，即：

这是 Baidu_ 的网址。.. _Baidu: https://www.baidu.com

在写 url 时可不能只写 www.baidu.com，这样 Sphinx 会以为 www.baidu.com 是一个具体文件地址，而非是网址

当我们写成如下时：

这是 Baidu_ 的网址。.. _Baidu: www.baidu.com

效果虽然和上述相同，但是点击后出现如下报错：

除了上述写法外，还有一种更为简单的写法：直接在名称后附加地址, 语法为 `别名 <链接>`_

这是 `Baidu <https://www.baidu.com>`_ 的网址。
5.1.2 匿名超链接

对于带别名的超链接而言，它只能是一个词语引用的文字不能带有空格。

当我们想要引用的文字中带有空格或者符号时，需要使用反引号引起来：

这篇文章参考的是：`Quick reStructuredText`__。.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html

5.2 锚点链接

内部超链接，即锚点。

锚点的语法：即外部超链接中带别名的超链接去除外部链接，其他语法一致。

更多信息参考 引用文档_这里是其他内容.. _引用文档:这是引用部分的内容

当我们点击引用文档后，网页会自动跳转到 .. _引用文档: 部分

5.3 间接链接

间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名。

示例如下:

Python_ is `my favourite programming language`__... _Python: http://www.python.org.. __: Python_

或者：

Python_ is `my favourite programming language`__... _Python: http://www.python.org__ Python_

其中 python_ 就是一个正常的外部链接

后面那句话是一个匿名链接， 对这个匿名链接使用间接链接方式链接到 Python这个外部链接的链接地址上去。

5.4 隐式超链接

小节标题、脚注和引用参考会自动生成超链接地址，使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。

例如链接到 《超链接Hyperlink Targets》 这个章节目录去：

超链接Hyperlink Targets-----------------------chapter1-----------------------chapter2-----------------------chapter3-----------------------chapter4-----------------------chapter5-----------------------chapter6-----------------------`超链接Hyperlink Targets`_

6. 文本块

6.1 文字块

文字块就是一段文字信息，指示符为连续两个冒号 :: ，支持文字块的嵌套。文字块支持三种形式的语法（完全等价）

  1. 起始新行，后接空行，块内容需缩进

    :: 缩进后填写块内容

  2. 正文写完后，不另起行，加一个空格，而后写双冒号，块内容同样缩进

    这里是前面内容，下面引用。 :: 缩进后填写块内容

  3. 正文写完后，不另起行，不空格紧接着直接写双冒号，块内容同样缩进。这样会保留一个冒号显示：

    这里是前面内容，下面引用:: > 在（部分/完全）简化形势下支持单行引用形式的嵌套 > 再来一个单行引用

也可以不是用缩进的方式，直接以单个符号，例如 > ? / * - + 等开头，亦可以实现文字块

6.2 行块

行块使用 | 指示符， 一般用于描述地址，歌词，诗歌，简单列表等。

**《忆江南》之二** --- 白居易| 江南忆，最忆是杭州。| 山寺月中寻桂子，郡亭枕上看潮头。| 何日更重游？

6.3 块引用

块引用是 通过缩进来实现 的，引用块要在前面的段落基础上缩进。

通常引用结尾会加上出处 (attribution)，出处的文字块开头是两个或者三个连续短横（”–“,”—”）后面加上出处信息。

块引用可以使用空的注释 .. 分隔上下的块引用。

注意在新的块  和  出处都要添加一个空行。

实际效果：    “真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。”    --- 鲁迅..    “人生的意志和劳动将创造奇迹般的奇迹。”    -- 涅克拉索

6.4 文档测试块

文档测试块是交互式的Python会话，以 >>> 开始，一个空行结束，是一种特殊的文字块，内容不需要缩进 。

可直接复制到python的 docstrings中，用于为doctest模块提供测试环境。

当文字块语法和文档测试块语法同时出现时，文字块语法优先级更高。

>>> print('this is a Doctest block')this is a Doctest block

7. 特殊提示

特殊提示支持警告、重要、提示、注意等标签，适合做显眼的用途。

  • attention
  • caution
  • danger
  • error
  • hint
  • important
  • note
  • tip
  • warning

语法：

.. note:: This is a note admonition. This is the second line of the first paragraph. - The note contains all indented body elements   following. - It includes this bullet list... hint:: This is a hint admonition... important:: This is a important admonition... tip:: This is a tip admonition... warning:: This is a warning admonition... caution:: This is a caution admonition... attention:: This is a attention admonition... error:: This is a error admonition... danger:: This is a danger admonition.

8. 代码高亮

8.1 快速定义代码块

使用简便的预定义高亮语法高亮缩进，默认不带语言说明的都使用highlight定义的语言高亮，然后可以直接使用 :: 两个冒号代替 code-block 指令快速定义其它代码块， 直到下一个 highlight 指令，才会改变语言：

.. highlight:: sh此指令后如下的 ``::`` 定义的块都会以 sh 语法进行高亮，直到遇到下一条 ``highlight`` 指令。::   #此命令在主机执行   sudo apt install python   echo "helloworld,this is a script test!"

8.2 code-block代码高亮

我们也可以用标准的 code-block 模式对 shell 高亮测试：

.. code-block:: sh   #此命令在主机执行   sudo apt install python   echo "helloworld,this is a script test!"

接下来我们对于这个代码块进行一些设置：

.. code-block:: sh   :caption: test   :name: test333   :emphasize-lines: 2   :linenos:   #此命令在主机执行   sudo apt install python   echo "helloworld,this is a script test!"
  • caption：添加标题
  • name：添加一个名称，可以用于隐式超链接
  • emphasize-lines：高亮行
  • linenos：行号

我们再放一个例子：

.. code-block:: c   :caption: c test   :emphasize-lines: 4-5, 8-9   :linenos:   #include <stdio.h>   int main()   {      printf("hello, world! This is a C program.\n");      for(int i=0;i<10;i++ ){         printf("output i=%d\n",i);      }      return 0;   }

8.3 嵌入整个文件

我们也可以直接将整个文件中的所有代码嵌入到文档中。

为了实现这个目的，我们首先新建一个名为 hello.c 的文件，并将下面内容填入其中：

/* $begin hello */#include<stdio.h>intmain(){printf("hello, world! This is a C program.\n");for(int i=0;i<10;i++ ){printf("output i=%d\n",i);    }return0;}/* $end hello */

然后我们将该文件直接纳入文档：

.. literalinclude:: ./hello.c   :caption: ./hello.c   :name: hello.c   :language: c   :emphasize-lines: 5,7-12   :linenos:

可以看到，所有内容都被完美纳入其中，并且也按照要求实现了高亮需求。

需要注意的是，我们需要在代码块的设置中，指定代码文件的编写语言。

此外，我们可能还会遇到一些情况，有时候我们想要插入代码文件中的一部分代码，而非全部。此时我们可以通过lines指定嵌入文件的某些行。例如：

.. literalinclude:: ./hello.c   :caption: ./hello.c (part)   :lines: 1,3,5-8   :name: hello_part.c   :language: c   :emphasize-lines: 1,2,4   :linenos:

8.4 文件对比

此外，我们也可以直接在文档中进行2个代码文件的差异比较。

为了演示，我们同样再新建一个名为 hello_diff.c 的文件，并将下面内容填入其中：

/* $begin hello */#include<stdio.h>intmain(){    print("hello, world! This is a C program.\n");for(int i=0;i<10;i++ ){printf("output i=%d\n",i);    }return0;}/* $end hello */

然后我们通过在文档中写入下面代码实现文件的比较：

.. literalinclude:: ./hello.c   :diff: ./hello_diff.c

9. 添加图片

图片原文件统一存储在文档所在的同级目录文件夹下。

显示图片直接使用 image 或 figure 指令，无特殊情况的话我们书籍图片要求使用居中方式显示， 还需要添加 alt 选项指定图片的描述，用于网站中使用，以便图片加载失败时显示文字。

推荐使用 figure 命令插入图片。

不要使用bmp图片 ，bmp图片在生成pdf的时候会丢失，所以不要使用bmp格式的图片。

9.1 使用 image 指令

直接给出一个具体例子：

.. image:: ./baidu.jpg   :align: center   :alt: Logo   :target: https://www.baidu.com   :height: 100 px   :width: 200 px   :scale: 120   :class: class-name   :name: name
  • align：可选top, middle, bottom, left, center, right
  • alt：当图片文件出现问题时，可以显示的内容。具体见下图。
  • target：使得图片可点击跳转
  • height：高度，后面给出具体单位，可以是px, in等
  • width：宽度，后面给出具体单位，可以是px, in等
  • scale：表示等比例伸缩
  • class：主要用于定义HTML中的对象
  • name：主要用于定义HTML中的id

9.2 使用 figure 指令

figure 命令的用法和 image 几乎一致，我们直接看一个例子：

.. figure:: baidu.jpg   :figwidth: 200 px   :scale: 50 %   :align: center   :alt: map to buried treasure

figure 支持 image 的所有指令选项参数，除了 align 在 figure 中指示整个画布的对齐方式。 且它只能选择为left, center, right。

10. 表格

reStructureText提供两种表格：网格表格（Grid Tables）， 简单表格（Simple Tables）。

表格前后都需要空行。

10.1 网格表格

  • “-” 分隔行(短破折号，减号)
  • “=” 分隔表头和表体行
  • “|” 分隔列
  • “+” 表示行和列相交的节点

网格表格注意点：

  • 行和列都支持并格
  • 如果文本内包含”|” ，并且恰好与表格内分隔对齐了，那么会产生错误。解决方案：方式一是加空格避免对齐，方式二是为该行增加一行
  • 可以不包含表头。
  • 列需要和”=”左对齐，不然可能会导致出错
  • 如果碰到第一列为空，需要使用 “\” 来转义, 不然会被视为是上一行的延续。
+------------------------+------------+----------+----------+| Header row, column 1   | Header 2   | Header 3 | Header 4 || (header rows optional) |            |          |          |+========================+============+==========+==========+| body row 1, column 1   | column 2   | column 3 | column 4 |+------------------------+------------+----------+----------+| body row 2             | Cells may span columns.          |+------------------------+------------+---------------------+| body row 3             | Cells may  | - Table cells       |+------------------------+ span rows. | - contain           || body row 4             |            | - body elements.    |+------------------------+------------+---------------------+

10.2 简单表格

简单表格使用 “=” 和 “_” 来进行绘制：

  • ”=” ：放置于表格的最外两行（首行和末行），如果有表头，则表头也用该符号进行分隔
  • ”_” ：用于跨列合并（column span）

简单表格需要各列首字母与该列指示的”=”对齐（表头可不对齐，为了保持统一，尽量保持左对齐），每列的 ”=” 需要覆盖该列字符的长度

我们还是用一个简单的有表头的例子来解释：

=====  =====  =======A      B      A and B=====  =====  =======False  False  FalseTrue   False  FalseFalse  True   FalseTrue   True   True=====  =====  =======

我们再用一个简单的没有头的例子来解释：

=====  =====  =======False  False  FalseTrue   False  FalseFalse  True   FalseTrue   True   True=====  =====  =======

我们再给一个简单的合并多列的例子来解释：

=====  =====  ======合并两列       单独列------------  ------A      B      A or B =====  =====  ======True   False  FalseFalse  True   FalseTrue   True   True=====  =====  ======

最后，我们再给一个简单的存在多行的例子来解释：

=====  ===================================col 1  col 2=====  ===================================1      Second column of row 1.2      Second column of row 2.       Second line of paragraph.3      - Second column of row 3.       - Second item in bullet         list (row 3, column 2).\      Row 4; column 1 will be empty.=====  ===================================

11. 数学表达式

reStructuredText 中支持的数学表达式使用 LaTeX 语法。 对使用 LaTeX 书写数学表达式不熟悉的读者可以在网络上找到许多入门语法。

我比较常用的是：https://xmind.cn/faq/question/equation

11.1 行内数学表达式

行内数学表达式是内嵌于文本中，不单独成行的表达式。直接使用角色 :math: ， 例如：

:math:`sin\alpha`

又或者我们将其直接放在段落中：

公式前文字 :math:`sin\alpha` 公式后文字。

11.2 行间数学表达式

行间数学表达式是指独立成行的表达式。

reStructuredText 语法中使用 math 指令（ 关于 “指令” 和 “角色” 这2个功能在下面的章节会进行简要介绍）来插入行间数学表达式。

数学表达式语法上与 LaTeX 的原生命令一致。

单行公式可以直接写在指令的同一行，比如：

单行公式可以直接写在指令的同一行，比如：.. math:: a + b = c

行间数学表达式示例代码

.. math::    f'(x) = \lim_{\triangle x \to 0} \frac{f(x + \triangle x) - f(x)}{\triangle x}

在 Sphinx 输出 HTML 时，建议在 conf.py 中加载 sphinx.ext.mathjax 插件。

此外，我们也可以使用 & 与 \\ 进行标记的对齐多行公式：

.. math::    (a + b)^2 &= (a + b)(a + b) \\              &= a^2 + 2ab + b^2

&=：对齐 =

\\：换行

12. 角色与指令

12.1 角色

role的格式为：:role名: 内容

角色包括：

  • 交叉引用： :any: ， :doc: ， :download: ， :envvar: ，
    :keyword: ，:numref: ， :option: ， :ref: ， :term: ， :token:
  • 行内高亮： :code:
  • 数学表达： :math: ， :eq:
  • 其他语义角色： :abbr: ， :command: ， :dfn: ， :file: ，
    :guilabel: ， :kbd: ， :mailheader: ， :makevar: ， :manpage: ， :menuselection: ， :mimetype: ， :newsgroup: ， :program: ， :regexp: ， :samp: ， :pep: ， :rfc:

Sphinx中的点位符也是角色，但使用的语法相对特殊，包括： |release| ， |version| ， |today| ， |translation progress|

12.2 指令

指令（Directives）是reStructureText的扩展机制。 可以在不增加新语法的情况下，增加新的结构性支持。

指令由三部分组成，格式为：

.. directive-type:: directive-block    :参数:    :参数:    ...    content

指令内容体又由三部分组成

  • 指令作用对象Directive arguments：指明该指令针对哪个对象作用
  • 指令选项参数Directive options：该指令的可选参数（可选），是一个参数列表
  • 指令内容说明Directive content：说明文档（可选）

比如插入一个图片

.. figure:: 图片名.png  # 这里是指令作用对象    :scale: 50     # 这里是指令参数    :width: 100    这是一个图片   # 这里是说明

通用指令选项参数

参数
作用
:class:
类型
:name:
为指令设置名称（可用于简化别名链接）

例如：

.. image:: baidu.jpg:name: my pic:height: 100px:width: 300px# 可以通过下面的方式，点击后返回到图片处`my pic`_# 简化方式，但是没法进行引用.. image:: baidu.jpg

Sphinx支持的指令：

  • 目录： .. toctree:: ，
  • 段落级别标识，如 Admonitions, messages, and warnings， 包括： .. attention:: ， .. caution:: ， .. danger:: ， .. error:: ， .. hint:: ， .. important:: ， .. note:: ， .. tip:: ， .. warning:: ， .. admonition:: title ， .. seealso:: 。
  • 版本变动指令： .. versionadded:: version [brief explanation] ， .. versionchanged:: version [brief explanation] ， .. deprecated:: version [brief explanation] ， .. versionremoved:: version [brief explanation] 。
  • 呈现方式（Presentational）： .. rubric:: title ， .. centered: ， .. hlist:: 。
  • 代码高亮指令： .. highlight:: language ， .. code-block:: [language] ， .. sourcecode:: [language] ， .. code:: [language] ， .. literalinclude:: filename 。
  • 词汇表： .. glossary:: 。
  • 元信息标识 ： .. sectionauthor:: name ， .. codeauthor:: name 。
  • 索引生成标识 ： .. index:: ， 这个得配合使用 :index: 。
  • 基于标签的内容包含指令： .. only:: 。

还有一类也属于指令，但语法不一样。 在Sphnx中用作特殊文档： genindex ， modindex ， search ， 以及以 _ 开头的名称。 Sphinx 使用这些保留名称用以特殊作用，创建文件时不要使用这些名称。

13. 脚注

脚注有三种形式：

  1. 手工序号(标记序号 1 ， 2 ， 3 之类)
  2. 自动序号(填入 # 号会自动填充序号)
  3. 自动符号(填入 * 会自动生成符号)

下面我们分别学习下这几种方法的用法。

13.1 手工序号

示例如下：

Footnote references, like [5]_.Note that footnotes may get [3]_rearranged, e.g., to the bottom ofthe "page"... [5] A numerical footnote. Note   there's no colon after the ]... [3] 脚注3

13.2 自动序号

示例如下：

自动排序脚注, like using [#]_ and [#]_... [#] This is the first one... [#] This is the second one.

此外，我们也可以自定义编号：

They may be assigned 'autonumberlabels' - for instance,[#ref2]_ and [#ref1]_... [#ref1] reference1.. [#ref2] reference2

13.3 自动符号

示例如下：

自动脚注符号, like this: [*]_ ,[*]_ , [*]_ and [*]_... [*] This is the first one... [*] This is the second one... [*] This is the third one... [*] This is the fourth one.

14. 目录

对于单个文件，或者网页的目录而言，我们一般使用 .. contents::，示例如下：

.. contents::     :local:=======C1=======Content1-------C1.1-------Content2*******C1.1.1*******Content3*******C1.1.2*******

这里需要和另外一个指令做出区分：.. toctree:: 。两者之间的区别在于：

  • .. toctree::
    ：生成跨文档的目录树（用于连接多个 .rst 文件）
  • .. contents::
    ：生成当前文档的章节目录。

15. 不同文档之间相互引用

当你同时有多个文档，并且想在目前文档中跳转到其他文档时，我们可以用下面的语法。

演示前，我们要先确保在目前文档目录下，存在一个文档，名为 about.rst。然后我们写如下内容：

# 自定义引用文字:doc:`自定义引用文字 <about>`# 使用标题文字:doc:`about`

有2个地方需要注意：

  • 指定路径时，以当前文档作为当前目录
  • 对于目标文档，不要写后缀。例如目标文档的文件名 about.rst，在书写时我们只能写为 about，而不能是 about.rst

后记

这里我们学习了一些构建文档时的语言 reStructuredText ，至此我们已经完整掌握了构建工具和语法的使用，接下来我们即将学习如何将构建好的文档托放到网络~

AD：【资源若失效或者不可用，请留言评论或加老夜微信 al_tmen】>>点此前往<<
本站文章均为手工撰写未经允许谢绝转载：夜雨聆风 » 使用Sphinx构建软件说明书(5):reStructuredText语法
xiaoqiang, wang

wang

猜你喜欢

评论 抢沙发

取消

3 + 3 =
  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
×
订阅图标按钮