Sphinx(3)RST语法
Author：Once Day Date：2025年11月21日
漫漫长路，才刚刚开始...
全系列文章请查看专栏: CS小白之路_Once-Day的博客-CSDN博客
参考文档:
- Sphinx --- Sphinx 文档 - Sphinx 文档生成器
- Sphinx + Read the Docs 从懵逼到入门 - 知乎
- 使用 Sphinx 高效生成项目文档：从入门到实战-CSDN博客
- 1. sphinx介绍 --- sphinx 文档
- Sphinx Themes Gallery
- 入门 --- Sphinx 文档 - Sphinx 文档生成器
- reStructureText语法
文章目录
-
-
- Sphinx(3)RST语法
-
- [1. 介绍](#1. 介绍)
- [2. 语法](#2. 语法)
-
- [2.1 标题与章节标记](#2.1 标题与章节标记)
- [2.2 段落](#2.2 段落)
- [2.3 无序列表](#2.3 无序列表)
- [2.4 有序列表](#2.4 有序列表)
- [2.5 定义列表](#2.5 定义列表)
- [2.6 字段列表](#2.6 字段列表)
- [2.7 参数(选项)列表](#2.7 参数(选项)列表)
- [2.8 文字块(Literal Blocks)](#2.8 文字块(Literal Blocks))
- [2.9 行块 Line Blocks](#2.9 行块 Line Blocks)
- [2.10 块引用 Block Quotes](#2.10 块引用 Block Quotes)
- [2.11 文档测试块](#2.11 文档测试块)
- [2.12 网格表格](#2.12 网格表格)
- [2.13 简单表格](#2.13 简单表格)
- [2.14 分隔符](#2.14 分隔符)
- [2.15 脚注 Footnotes](#2.15 脚注 Footnotes)
- [2.16 引用 Citations](#2.16 引用 Citations)
- [2.17 超链接 Hyperlink Targets](#2.17 超链接 Hyperlink Targets)
- [2.18 内联标记 Inline Markup](#2.18 内联标记 Inline Markup)
- [2.19 反斜杠转义 Escaping with Backslashes](#2.19 反斜杠转义 Escaping with Backslashes)
- [3. 扩展指令 Directives](#3. 扩展指令 Directives)
-
- [3.1 警告信息Admonitions](#3.1 警告信息Admonitions)
- [3.2 图片Images](#3.2 图片Images)
-
1. 介绍
reStructuredText(简称RST)是一种轻量级标记语言，专为技术文档设计。它于2002年由David Goodger创建，作为Python文档系统的一部分，后来成为Docutils项目的基础。
RST的出现源于技术文档领域对简单且可读性强的标记语言的需求。在RST出现之前，HTML过于复杂，而纯文本又缺乏足够的表现力。Goodger设计RST时，特别注重了"所见即所得"的理念------即使在原始文本状态下，RST文档也应该清晰易读。
Python社区对RST的采纳使其迅速流行。它成为Python官方文档系统Sphinx的默认格式，这大大促进了RST的传播。随后，许多其他项目也采用了RST作为文档格式，包括多个开源项目和企业文档系统。
RST的设计理念强调简洁性、可读性和扩展性。它提供了基本的格式化功能，如标题、列表、表格和引用，同时也支持更高级的功能，如交叉引用、图像嵌入和代码块。虽然与Markdown相比可能学习曲线稍陡，但RST在复杂文档结构和技术文档方面提供了更强的表现力。
2. 语法
2.1 标题与章节标记
RST使用下划线和可选的上划线来标记标题。任意可打印的7位ASCII字符都可以作为章节标识符，包括：
rst
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~不过推荐使用以下字符：
rst
= - ` : . ' " ~ ^ _ * + #RST中未明确规定各个章节标识符的层级顺序，它按照标识符在文档中首次出现的顺序来确定层级。可以选择在标题上下各使用一行标识符，或只在标题下使用一行标识符，效果相同。标识符的数量必须至少与标题文本等长。
建议的标题层级定义(从高到低)：
rst
一级标题
==========
二级标题
----------
三级标题
,,,,,,,,,
四级标题
............
五级标题
*************2.2 段落
在 RST 文档中，段落是文档的基本构建块：
- 段落是左对齐的文本块，没有特殊的标记或格式
- 段落之间必须用空行分隔，这是 RST 识别不同段落的方式
- 如果一个段落相对于周围内容缩进（如缩进4个空格），RST 会将其解析为"引用段落"(quote paragraph)，这种段落在显示时会有特殊的样式
引用段落通常用于引用他人的话或想要强调的内容，在最终渲染的文档中会有不同的视觉效果，比如可能会有缩进或不同的背景色。
2.3 无序列表
reStructuredText 的无序列表语法与 Markdown 相似，主要使用 +, -, * 作为列表标识符，通过缩进表示嵌套关系。
无序列表的语法规则：
- 列表的起始和结束前后需要空行。
- 同级列表项之间空行可加可不加。
- 不同层级的列表项之间必须加空行。
- 列表项中如有多段内容，后续段落不需要重复列表标识符，只需保持相同缩进。
- 可以混用不同的标识符，但建议同级使用相同符号，推荐层级顺序为
+,-,*。
rst
+ 一级列表第一项
+ 一级列表第二项
- 二级列表，换层级加空行
二级列表的第二段内容，加空行，缩进对齐
+ 依然是二级列表，指示标识符可以混用，但不推荐
* 第三级渲染效果：
-
一级列表第一项
-
一级列表第二项
-
二级列表，换层级加空行
二级列表的第二段内容，加空行，缩进对齐
-
依然是二级列表，指示标识符可以混用，但不推荐
- 第三级
-
2.4 有序列表
有序列表，也称为枚举列表或顺序列表(ordered-list)，允许使用不同类型的序号来标记列表项。
RST 支持以下几种枚举指示符：
- 阿拉伯数字: 1, 2, 3, ... (无上限)。
- 大写字母: A, B, C, ... Z。
- 小写字母: a, b, c, ... z。
- 大写罗马数字: I, II, III, IV, ... MMMMCMXCIX (4999)。
- 小写罗马数字: i, ii, iii, iv, ... mmmmcmxcix (4999)。
每种枚举类型可以使用不同的前缀和后缀：
- 点号后缀: "1.", "A.", "a.", "I.", "i."。
- 圆括号包围: "(1)", "(A)", "(a)", "(I)", "(i)"。
- 右括号后缀: "1)", "A)", "a)", "I)", "i)"。
可以使用 # 符号实现自动编号，系统会自动递增序号。
当普通文本以可能被识别为列表的形式开头时，可以采取以下措施避免被解析为列表：
- 将一行内容拆分为多行（会被识别为段落而非列表）。
- 使用反斜杠
\在段首进行转义。
避免列表识别的例子：
css
A. Einstein was a really
smart dude. （跨行避免）
A. Einstein was a really smart dude.（未避免）
\A. Einstein was a really smart dude.（使用\转义）效果：
- "A. Einstein was a really smart dude." (正常文本)
- " A. Einstein was a really smart dude." (被识别为列表，A 成为了列表编号)
- "A. Einstein was a really smart dude." (使用转义后正常显示)
有序列表也支持嵌套，规则与无序列表一致：
apache
1. Item 1 initial text.
a) Item 1a.
b) Item 1b.
#. a) Item 2a.使用#号自增
b) Item 2b.效果：
- Item 1 initial text.
a) Item 1a.
b) Item 1b. - a) Item 2a.使用#号自增
b) Item 2b.
注意：不同级别之间需要空行，同级别列表项之间空行可加可不加。后续段落需保持与列表标识符相同的缩进级别。
2.5 定义列表
定义列表可以理解为解释列表或名词解释，用于提供术语及其定义。在 reStructuredText 中，这种列表有特定的格式和结构。
每个定义列表项由三个部分组成：
- 条目名称 (term) - 要定义的名词或短语。
- 条目属性 (classifier) - 可选，对条目的分类说明。
- 条目定义 (definition) - 对条目的解释或定义。
格式规则：
- 条目名称单独占一行。
- 条目属性与条目名称在同一行，通过空格、冒号、空格
" : "连接。 - 一个条目可以有多个属性，各属性之间也用
" : "连接。 - 条目定义必须另起一行，并有缩进。
- 定义可以包含多个段落，保持相同缩进即可。
- 多层定义可以通过不同级别的缩进实现。
示例代码：
rst
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.渲染效果：
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.
定义列表特别适合用于：
- 术语表和词汇解释
- 参数说明文档
- API 文档中的参数详解
- 任何需要名词解释的场景
定义列表的灵活性使其成为技术文档中非常有用的一种结构，尤其是在需要详细解释概念的情况下。
2.6 字段列表
字段列表在 reStructuredText 中是一种特殊的列表格式，主要用于指令解释或数据库字段（记录）解释的场景。它的呈现形式类似于两列表格，使其特别适合于展示属性和值的对应关系。
字段列表的特点：
- 格式像两列表格，左侧为字段名，右侧为字段值。
- 字段名以冒号开始和结束
:fieldname:。 - 字段体(field body)具有与表格单元格相似的功能。
- 支持嵌套和跨行等复杂结构。
格式规则：
- 字段名必须以冒号开始和结束。
- 字段名可以是短语(phrase)，即可以包含空格，但不能包含冒号
:。 - 字段体可以在同一行，也可以缩进到下一行。
- 如果字段体跨多行，第一行后的所有行必须保持相同缩进。
- 字段体的第二行不必与第一行左对齐，但后续行必须与第二行对齐。
示例代码：
rst
:Date: 2020-02-02
:Version: 1
:Authors: - 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: field name可以是phrase，即可以带空格，但是不能带":"效果如下：
2.7 参数(选项)列表
参数列表是 reStructuredText 中一种特殊的双栏列表格式，专门用于展示命令行参数及其说明。这种格式在技术文档、命令行工具的帮助文档中特别常见。
参数列表的特点：
- 左列为参数名称，右列为参数说明
- 没有表头，直接展示参数和说明
- 专为命令行参数设计的格式化结构
- 支持多种常见的命令行参数格式
参数列表支持三种主要的参数书写形式：
- POSIX 短格式 ：由一个短横线连接，如
-a - POSIX 长格式 ：由两个短横线连接，如
--long - DOS/VMS 格式 ：由斜杠开始的格式，如
/V
格式规则：
- 参数和说明间用空白分隔
- 参数可以包含参数值，如
-b file或--input=file - 说明文本可以跨多行，需要保持缩进对齐
- 每个参数项独占一行
示例代码：
rst
-a command-line option "a"
-b file options can have arguments
and long descriptions
--long options can be long also
--input=file long options can also have
arguments
/V DOS/VMS-style options too效果如下：
2.8 文字块(Literal Blocks)
文字块是 reStructuredText 中用于呈现预格式化文本的方式，常用于代码片段、命令输出等需要保持原始格式的内容。文字块中的文本会按原样显示，保留空格、换行等格式。
文字块的特点：
- 使用连续两个冒号
::作为指示符。 - 文字块中的文本会按原样显示，保留所有空格和换行。
- 适合展示代码、配置文件等预格式化内容。
- 支持嵌套结构。
文字块的三种语法形式：
（1）完整形式：
起始行为双冒号，后接空行，块内容需要缩进：
rst
::
缩进后填写块内容（2）部分简化形式：
前文带一个冒号，加一个空格后，双冒号接在前文后面：
rst
这里是前面内容，下面引用: ::
缩进后填写块内容（3）完全简化形式：
双冒号直接接在前文后面，显示时转换为单冒号：
rst
这里是前面内容，下面引用::
> 在（部分/完全）简化形势下支持单行引用形式的嵌套
> 再来一个单行引用效果如下：
2.9 行块 Line Blocks
行块是 reStructuredText 中一种特殊的文本格式，专门用于保留文本的行结构，同时仍然允许使用RST的文本格式化特性。这与文字块不同，文字块完全按原样显示，而行块在保留行结构的同时允许文本格式化。
行块的特点：
- 使用竖线符号
|作为每行的开始标记。 - 保留文本的行结构和换行。
- 允许在行内使用RST的文本格式化(如粗体、斜体等)。
- 行内的空格也会被保留。
行块的语法：
每个行块的行都以竖线符号 | 开始，后面跟一个空格，然后是行内容：
rst
| 行块使用 | 指示符，
| 一般用于描述地址，歌
词，诗歌，简单列表等。格式规则：
- 每行以竖线符号
|开始。 - 通常在竖线后跟一个空格（不是必须的，但建议使用）。
- 行的延续可以通过在下一行开始处缩进来实现（如示例中的第三行）。
- 行内空格会被保留。
- 空行用单独的
|表示。
效果如下：
yacas
行块使用 | 指示符，
一般用于描述地址，歌
词，诗歌，简单列表等。2.10 块引用 Block Quotes
块引用是 reStructuredText 中通过缩进来实现的文本格式，用于引用他人的话语或其他来源的内容。它与普通段落不同，通过缩进来视觉上区分引用内容。
块引用的特点：
- 通过缩进来实现，无需特殊标记符。
- 可以添加出处(attribution)。
- 可以包含多个段落。
- 多个块引用可以通过空注释分隔。
格式规则：
- 块引用通过缩进实现，引用内容相对于前面的段落要有缩进。
- 引用出处在引用内容之后，以两个或三个连续短横线（"--"或"---"）开始。
- 引用内容和出处之间需要添加空行。
- 多个块引用之间可以用空注释
..分隔。 - 在新的块和出处前都要添加一个空行。
当需要连续使用多个块引用时，可以使用空注释 .. 来分隔它们，确保它们被识别为独立的块引用。
基本结构是在普通段落的基础上增加缩进（通常是4个空格）：
rst
"真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。"
--- 鲁迅
..
"人生的意志和劳动将创造奇迹般的奇迹。"
-- 涅克拉索实际效果：
2.11 文档测试块
文档测试块是交互式的Python会话，以 >>> 开始，一个空行结束，是一种特殊的文字块，内容不需要缩进 。
可直接复制到python的 docstrings中，用于为doctest模块提供测试环境。
当文字块语法和文档测试块语法同时出现时，文字块语法优先级更高。
rst
>>> print('this is a Doctest block')
this is a Doctest block2.12 网格表格
格式规则：
- "-" 分隔行(短破折号，减号)
- "=" 分隔表头和表体行
- "|" 分隔列
- "+" 表示行和列相交的节点
网格表格注意点：
- 网格表格编辑复杂，可以使用Emacs来编辑生成。
- 行和列都支持并格。
- 如果文本内包含"|" ，并且恰好与表格内分隔对齐了，那么会产生错误。方法一是加空格避免对齐，方法二是为该行增加一行。
- 可以不包含表头。
- 列需要和"="左对齐，不然可能会导致出错。
- 如果碰到第一列为空，需要使用 "" 来转义, 不然会被视为是上一行的延续。
示例：
rst
+------------------------+------------+----------+----------+
| 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. |
+------------------------+------------+---------------------+实际效果：
2.13 简单表格
简单表格使用 = 和 _ 来进行绘制，其中=放置于表格的最外两行（首行和末行）,如果有表头，则表头也用该符号进行分隔，_用于跨列合并（column span）。
简单表格需要各列首字母与该列指示的=对齐(表头可不对齐，为了保持统一，尽量保持左对齐)，每列的=需要覆盖该列字符的长度
包含表头的简单表格：
rst
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======效果如下：
| A | B | A and B |
|---|---|---|
| False | False | False |
| True | False | False |
| False | True | False |
| True | True | True |
无表头的简单表格：
rst
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======效果如下：
| False | False | False |
|---|---|---|
| True | False | False |
| False | True | False |
| True | True | True |
跨列合并：_用于跨列合并，仅支持在表头使用 ，_长度需要从起始列的第一个指示符=到终止列的最后一个指示符=。
rst
===== ===== ======
合并两列 单独列
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======效果如下:
单个表格中可以多行：
- 简单表格的单个格子中可以包含多行的内容（比如列表），但是不支持行合并；
- 增加空行可以进行换行，否则会自动将文本连接在一起。
- 首列不能为空，为空时使用 \ 进行占位。
rst
===== ===================================
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.
===== ===================================效果如下：
2.14 分隔符
转换分隔用于段与段之间的分隔，相当于html中的hr，就是跨屏的一个横线。
使用4个及以上的标点符号(推荐使用短横 "-")就可以生成，同样需要前后空行，另外，不能连续出现 ，不能在文档结尾使用。
rst
前后需要空行
,,,,,,,,
使用标点符号
.............
不能连续出现
---------------
不能在结尾使用效果如下：
2.15 脚注 Footnotes
脚注有三种形式， 手工序号(标记序号123之类)、自动序号(填入 # 号会自动填充序号)、自动符号(填入 * 会自动生成符号)
手工序号可以和 # 结合使用，会自动延续手工的序号。
#表示的方法可以在后面加上一个名称，这个名称就会生成一个链接。
（1）手工标序(标记序号123之类)：
rst
Footnote references, like [5]_.
Note that footnotes may get [3]_
rearranged, e.g., to the bottom of
the "page".
.. [5] A numerical footnote. Note
there's no colon after the ].
.. [3] 脚注3效果如下：
（2）自动序号(填入 # 号会自动填充序号)：
rst
自动排序脚注, like using [#]_ and [#]_.
.. [#] This is the first one.
.. [#] This is the second one.效果如下：
可以添加别名，即可同时实现自动排序，又带有自定义名称，这个功能相当于实现了文献引用功能。
rst
They may be assigned 'autonumber
labels' - for instance,
[#fourth]_ and [#third]_.
.. [#third] a.k.a. third_
.. [#fourth] a.k.a. fourth_效果如下：
（3）自动符号(填入 * 会自动生成符号)：
自动填符号功能上和自动填序号是一样的，只是换了一种辨识符号。
rst
自动脚注符号, like this: [*]_ ,[*]_ , [*]_ and [*]_.
.. [*] This is the first one.
.. [*] This is the second one.
.. [*] This is the third one.
.. [*] This is the fourth one.效果如下：
2.16 引用 Citations
引用和脚注是一样的，只不过引用只能用文本而不能用数字。
rst
引用参考的内容通常放在页面结尾处，比如 [One]_，Two_
.. [One] 参考引用一
.. [Two] 参考引用二效果如下：
2.17 超链接 Hyperlink Targets
超链接 Hyperlink 有三种：
- 带别名的超链接 ，语法为
.. _hyperlink-name: link-address；由..，空格，短下划线_，别名，冒号，空格和链接地址构成。 在原文引用处书写语法为hyperlink-name_（特别注意原文中_在别名后，而在指示链接出，_在别名前）。 - 匿名anonymous的超链接，即不带别名的超链接，语法为
.. __: link-address； 由..，空格，两个短下划线__，冒号，空格和链接地址构成。 - 匿名的超链接，另一种语法形式，语法为
__ link-address。
外部链接 External Hyperlink Targets有两种方式，需要引用的话，使用上述带别名的超链接的语法形式，即：
yacas
这是我的 reStructureText_ 实践笔记。
.. _reStructureText: https://sphinx-practise.readthedocs.io/zh_CN/latest/index.html另一种是直接在名称后附加地址, 语法为 ``别名 <链接>_
rst
这是我的 `reStructureText <https://sphinx-practise.readthedocs.io/zh_CN/latest/index.html>`_ 实践笔记。锚点链接 Internal Hyperlink Targets，内部超链接，即锚点。锚点的语法即外部超链接中带别名的超链接去除外部链接，其他语法一致。
间接链接 Indirect Hyperlink Targets，间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名。
yacas
Python_ is `my favourite
programming language`__.
.. _Python: http://www.python.org/
__ Python_其中 python_ 就是一个正常的外部链接，而后面那句话是一个匿名链接， 对这个匿名链接使用间接链接方式链接到 Python这个外部链接的链接地址上去。
效果如下：
隐式超链接 Implicit Hyperlink Targets，小节标题、脚注和引用参考会自动生成超链接地址，使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。本质上它们的写法都是和 外部链接 External Hyperlink Targets 相一致的, 只是做了一些微小改动，以做出区别。
例如链接到超链接Hyperlink Targets这个章节目录去
yacas
`超链接Hyperlink Targets`_2.18 内联标记 Inline Markup
2.19 反斜杠转义 Escaping with Backslashes
使用反斜杠来转义任意rst语法符号为符号本身，包括反斜杠自己
- 转义内联标记：
\*去除斜体* - 转义反斜杠（用两个反斜杠）：
\\
3. 扩展指令 Directives
指令（Directives）是reStructureText的扩展机制。 可以在不增加新语法的情况下，增加新的结构性支持(a way of adding support for new constructs)。
指令由三部分组成：
yacas
.. directive-type:: directive-block其中指令类型（directive-type）指明指令的类型，指令内容体又由三部分组成：
- 指令作用对象Directive arguments：指明该指令针对哪个对象作用。
- 指令选项参数Directive options：该指令的可选参数(可选)，是一个参数列表。
- 指令内容说明Directive content：说明文档(可选)。
比如插入一个图片：
yacas
.. figure:: 图片名.png # 这里是指令作用对象
:scale: 50 # 这里是指令参数
:width: 100
这是一个图片 # 这里是说明3.1 警告信息Admonitions
特定的警告信息，格式为：
rst
.. admonition:: admonition-title(可空)
:class: class-name(可选)
:name: name(可选)
admonition-content说明信息admonition-title和admonition-content显示效果是一体的， 但是admonition-title(可空)会在html中单独存在一个title标签中。
支持如下特定警告信息：attention，caution，danger，error，hint，important，note，tip，warning。
示例如下：
rst
.. attention:: This is a attention admonition.
second attention paragraph.
.. caution:: This is a caution admonition.
second caution paragraph.
.. danger:: This is a danger admonition.
second danger paragraph.
.. error:: This is a error admonition.
second error paragraph.
.. hint:: This is a hint admonition.
second hint paragraph.
.. important:: This is a important admonition.
second important paragraph.
.. 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.
.. tip:: This is a tip admonition.
second tip paragraph.
.. warning:: This is a warning admonition.
second warning paragraph.通用警告信息Generic Admonition：通用警告信息即不指定为特定的警告类别，使用admonition指代警告。 与特定警告不同的是，特定警告的admonition-title在通用警告中为admonition-name， 这是我们自定义的警告名，用于和特定警告（danger,hint,important等）提供同等标识。
rst
.. admonition:: And, by the way...
You can make up your own admonition too.3.2 图片Images
使用image：
rst
.. image:: picture.jpeg
:class: class-name
:name: name
:height: 100 px(长度)
:width: 200 px (长度或者百分比)
:scale: 50 % (百分比，百分号可省略)
:alt: alternate text
:align: right
:target: https://www.baidu.com-
align可选top,middle,bottom,left,center,right。
-
target使得图片可点击跳转。
-
scale表示等比例伸缩（放大或者缩小）。
-
scale需要和width或者height（或者2者）一起使用。
使用figure：
rst
.. figure:: picture.png
:figwidth: 200 px (长度或者百分比)
:scale: 50 %
:align: center
:figclass: figure-class
:alt: map to buried treasure
+---------------------------+
| figure |
| |
|<------ figwidth --------->|
| |
| +---------------------+ |
| | image | |
| | | |
| |<--- width --------->| |
| +---------------------+ |
| |
|The figure's caption should|
|wrap at this width. |
+---------------------------+figure相当于一个画布(类似于html中的一个div或者一个canvas)， 它对处于其内的内容进行样式统一管理。相比image可以包含除图片外的更多内容。
figure支持image的所有指令选项参数，除了align在figure中指示整个画布的对齐方式。 且它只能选择为left,center,right。
和image一致，要使得scale(这里是对整个画布作用)起作用需要和figwidth一起使用。