标题（一级标题）

reStructuredText（简称reST）的标题由标题名称和标题下的符号线组合而成。现统一规定各级标题的使用规范如下：

这里是一级标题。

一级标题下的符号线是 ========。

二级标题

这里是二级标题。

二级标题下的符号线是 --------。

三级标题

这里是三级标题。

三级标题下的符号线是 ~~~~~~~~。

四级标题

这里是四级标题。

四级标题下的符号线是 ^^^^^^^^。

五级标题

这里是五级标题。

五级标题下的符号线是 ********。

六级标题

这里是六级标题。

五级标题下的符号线是 ##########。

小心

reST的标题由标题名称和标题下的符号线组合而成，各标题级别的符号线样式全文统一。
各级标题下的符号线段长度不能小于标题长度，否则不能正确解析。
当不同rst文档中使用不同的标题符号线时，Sphinx的文档解析器（Docutils）依然可以根据符号的使用情况和上下文确定每个标题的级别，并映射到相应的级别，保持文档输出结构一致。

但是为了文档的规范性和一致性，请大家严格遵守规定，严格使用上文定义的各级标题符号线。

备注

各级标题的符号线段依次使用 = - ~ ^ * # 表示。
- 一级标题 ========
- 二级标题 --------
- 三级标题 ~~~~~~~~
- 四级标题 ^^^^^^^^
- 五级标题 ********
- 六级标题 ########
HTML只支持最多6级标题，一般已足够使用。
标题后续可以直接接正文，不用单独空一行。

reST 架构

文档目录/contents

使用 .. contents:: 指令添加目录。

参数释义

local:: 只显示当前文件而非整个文档的目录。
depth:: 指定目录的深度，默认情况下，除文档名外c的所有标题级别都被包括在内。

.. contents::
   :local:
   :depth: 2

备注

目录的位置建议放到文档顶部，置于文档名之后，这样可以生成整篇文档的架构。
目录样式已设置悬浮在网页右侧侧边栏显示。

目录树/toctree

使用 .. toctree:: 指令定义目录树。

目录树（toctree）是Sphinx用来表示文档内容的中间数据结构，是一种树形结构，包括所有文档元素以及它们之间的层级关系。

各层级的文档通toctree指令相互链接，以形成层级结构。

引用同层级目录下的文件，直接写文件即可
引用上层目录下的文件，使用 ../ 返回上一级目录，然后指定文件路径

参数释义

maxdepth:: 定义目录深度
hidden:: 目录仍会存在于Sphinx的文档结构中，但是不会在当前指令位置显示
numbered:: 在HTML中为章节编号
titlesonly:: 目录里仅出现文档的标题，不出现文中其他同等级的标题行

.. toctree::
   :maxdepth: 1
   :hidden:

   AT Command <rtos/sdk/at_command/index>

toctree添加文件的几种方式

rst文件名 直接引用当前路径下文件，无需添加.rst后缀，显示为文件内部文档名，而非文件名。
自定义标题 <rst文件名> 添加自定义显示名称。
自定义标题 <文件路径> 添加绝对或者相对路径，引用不同文件。
自定义标题 <其他toctree> 添加toctree嵌套，同样生效。
原则上所有文件都需出现在某个toctree指令里，否则Sphinx会报出警告，因为该文件没有通过标准导航。

基本元素

段落

段落是rst文件的基本模块，正文的段落用空行分隔，一律顶格书写，行首不得有空格。

如果没有空行，下一行的段落将紧跟上文，被视为连续文本。

缩进

缩进的段落

被认为是前面文本的引文。

保持相同的缩进为同一层级。

缩进取消，这段文字为新的段落（不用空行也可以被识别为新的段落）。

备注

在rst中，缩进非常重要，通过对缩进和空行的把控，可以调整文档的布局和格式。
rst中，要求每一层级的缩进量以上一层级为标准对齐。
- 大部分内容，为了与指令字符对齐，需要使用3个空格缩进，即每个层级缩进3个空格。
- 每当缩进量改变时，段落内容就进入了新的缩进层级。
- 请保持（相邻的）同级内容使用同样的缩进量，逐层缩进时尤其要注意缩进量。
- 图表的缩进如果不对，会导致图表无法正确显示。

列表/list

有序列表(ordered list)

在Sphinx中，以下用于标识有序列表的序号和格式都可以被正确识别和解析。

能识别的序号：
- 阿拉伯数字：1, 2, 3, …
- 大写字母：A, B, C, …, Z
- 小写字母：a, b, c, …, z
- 大写罗马数字：I, II, III, IV, …
- 小写罗马数字：i, ii, iii, iv, …
能识别的格式：
- 以句点为后缀：“1.”，“A.”，“a.”，“I.”，“i.”
- 用括号括起来：“(1)”，“(A)”，“(a)”，“(I)”，“(i)”
- 以右括号为后缀：“1)”，“A)”，“a)”，“I)”，"i)”

警告

虽然这些格式都能被识别，但是不可以混用，同一个多级有序列表仅可选用其中一种。
建议有序列表各层级依次使用以下序号和符号，并全文保持一致和统一。
1. 第一级：“1.”，“2.”，“3.”，...
  1. 第二级：“A.”，“B.”，“C.”，...
    1. 第三级：“a.”，“b.”，“c.”，...

以下为三级有序列表的示例：

父列表1
父列表2
1. 一级嵌套
2. 列表子项
  1. 二级嵌套
  2. 列表子项
父列表继续

无序列表(unordered list)

这是一个无序列表
这是父列表
- 一级嵌套
- 列表子项
  - 二级嵌套
  - 列表子项
父列表继续

备注

列表使用数字./* - +后续跟一个空格表示，也可以使用符号#.自动加序号。
列表可以嵌套，但是需跟父列表使用空行分隔，同时注意保持缩进。
空行：先检查一级嵌套与父列表存在空行，为两个段落。
缩进：再检查有无缩进，此处一级嵌套编号与父列表文本对齐没有缩进，在网页上整个列表呈现为一个整体，多级列表之间没有间隔。

常见问题

在无序列表中遇到的一些常见问题，几乎都与空行和缩进有关。

以下三个问题都是不正确的写法，原因基本都是因为空行和缩进不对。

问题一

* 这是一个
* 父列表

  * 一级嵌套
  * 列表子项

    * 二级嵌套
    * 列表子项

问题分析

空行：先检查一级嵌套与父列表没有空行，是连续的段落。
缩进：再检查有无缩进，此处一级嵌套编号与父列表文本没有缩进，对齐的段落被解析成连续的文本,*标记紧跟父列表文本，编号定义没有生效，所以在网页上直接显示符号。
二级嵌套编号与父列表存在缩进，被解析为父列表的一级嵌套。

问题二

* 这是一个
* 父列表

   * 一级嵌套
   * 列表子项

      * 二级嵌套
      * 列表子项

问题分析

空行：先检查一级嵌套与父列表没有空行，是连续的段落。
缩进：再检查有无缩进，此处一级嵌套编号与父列表文本存在缩进，缩进的段落被解析为上文的引文而单独一行（编号前面没有字符，定义生效），所以在网页上一级嵌套生效并被解读为父列表的引文，同理，二级嵌套被解析为列表子项的引文。

问题三

* 这是一个
* 父列表

   * 一级嵌套
   * 列表子项

      * 二级嵌套
      * 列表子项

问题分析

空行：先检查一级嵌套与父列表存在空行，为两个段落。
缩进：再检查有无缩进，此处一级嵌套编号与父列表文本存在缩进，所以在网页上嵌套列表与父列表呈现两个段落，中间有间隔。

定义列表(definition list)

定义列表可以用于名词解释。

功能: 这是一个功能描述。
注意事项: 这是注意事项描述。

例如：

term 1

Definition 1.

term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

term 3classifier

Definition 3.

term 4classifier oneclassifier two

Definition 4.

-term 5

Without escaping, this would be an option list item.

字段列表(field list)

字段列表可以用于函数说明。

例如：

Function Name:: ADC_DeInit
Function Prototype:: void ADC_DeInit(void)
Function Description:: Function Description
Input Parameter:: ADCx: Base Address of ADCx pointing to the ADC module selected
Output Parameter:: None
Return Value:: None
Prerequisite:: None
Functions Called:: RCC_PeriphClockCmd Function

参数列表(option list)

参数列表可以用于命令行中各参数说明。

-V: 简单参数
-h, --help: 以逗号分隔的参数
-c docname: 带空格的参数
--file=flag: 带等号的参数
--an-longer-arg: 有点长的参数
--an-arg-that-is-very-long: 过长的参数的说明文字，可以从第二行开始，注意对齐
/S: 斜线开头的参数

表格/table

网格表

网格表使用画图的方式绘制表格，做以下说明。

网格表中使用的符号如下：
- 用 - 来分隔行。
- 用 = 来分隔表头和表体行。
- 用 | 来分隔列。
- 用 + 来表示行和列相交的节点。
单元格内部支持段落、强调、链接等语法。
表格的引用通过:ref:指令实现，这是Table name，也可以自定义表格名称。

参数释义

table:: 表格标题
width:: 表格宽度
widths:: 表格各列列宽（设置为auto时自动调整列宽）
align:: 表格对齐方式（非单元格内容对齐方式）
name:: 表格标签，用于表格跳转

Table name
Heading	Heading	Heading
Contents	Contents	Contents
Contents	Contents	Contents (http://example.com)

合并单元格表
Heading	Heading	Heading
Heading	Heading
Contents	Contents	Contents
Contents	Cells may span columns. Cells may span columns.
Contents	Cells may span columns.	Contents Contents Contents
Contents	Cells may span columns.	Contents Contents Contents

备注

网格表的绘制必须保持每个单元格长度（主要是字符）一致，否则无法解析。
rst中涉及到单元格合并的表格建议使用网格表绘制。
当前文档表格单元格内容均设置左对齐，目前暂时无法对某一列单独做调整，需要自定义CSS功能。

在撰写reST文档时，可以借助一些工具辅助生成表格。以下是一些常见的工具和方法，可以直接将表格转换成rst能识别的语法。

Tables Generator

网站：Tables Generator

以下是 Tables Generator 转换示例。

Tables Generator 转换示例
H1	H2	H3	H4
C1	C2		C3
C4	C5	C6
	C7

Table Editor

网站：Tables Editor

Table Editor 支持将Excel等多种格式转换为reStructuredText表格。

以下是使用 Table Editor 转换的用法截图。

../_images/table_editor_usage.png — Table Editor转换用法

CSV表

参数释义

csv-table:: 表格标题
header:: 表格标题行
stub-columns:: 指定首列做标题
widths:: 表格相对宽度
align:: 表格对齐方式
name:: 表格标签

CSV表格举例
标题1	标题2	标题3
说明1	Xxx	Xxx
说明2	Xxx	Xxx
说明3	Xxx	Xxx
说明4	Hello, world!	"Hello, world!"

备注

标题行和数据行用英文逗号 , 进行分格，若单元格内容本身包含逗号，可用引号包含，如上示例 "Hello, world!"
如果数据中本身包含引号，那么需要使用两个连续的引引号来表示一个，如上示例 """Hello, world!"""
CSV表格也可以添加 :file: 参数引 .csv 文件直接插入表格。

List表

参数释义

list-table:: 表标题
header-rows:: 标题行数量（这边设置2级标题）
stub-columns:: 指定首列做标题
widths:: 表格相对宽度
align:: 表格对齐方式
name:: 表格标签

Listtable表格举例
标题1	标题2	标题3
次标题1	次标题2	次标题3
xxx	xxx	xxx
xxx	Hello, world!	"Hello, world!"

备注

线性表格内容无需用引号包含。

水平列表

使用 .. hlist:: 生成， :columns: 参数设置列数。

说明1
说明2

说明3
说明4

说明5
说明6

说明7
说明8

备注

该指令通常用于创建紧凑的列表，如一节结束时放置相关主题列表或者显示一系列小项列表以便紧凑、易读。

图片/figure/image

使用 .. figure:: 或 .. image:: 指令添加图片，以下参数均为可选。

参数释义

figure:: 图片路径，支持使用 .* 扩展名自动选择文件： .pgn .jpg .pdf
height:: 设置图片的高度，可以为具体像素px或者百分比
width:: 设置图片的宽度，可以为具体像素px或者百分比
scale:: 设置图片缩放比例，可以为数值或者百分比
align:: 图片对齐方式：center/left/right
alt:: 图片加载失败时的替代文本
name:: 图片标签，用于图片跳转

备注

注意区分图片标签与图片标题，使用figure指令时，图片标题在下方添加。

target:: 点击图片时跳转的链接，可以是绝对地址、相对地址，或者rst的超链接。

图片的引用通过 :ref: 指令实现，这是绿灯，也可以自定义图片名称。

图片标题 (红灯)

绿灯

备注

figure和image的主要区别在于：image指令无法添加图片标题，其余参数和figure指令一致。
height, width和scale属性不要同时使用。建议规范截图，之后使用scale属性控制图片的显示尺寸。
每份文档的图片均存放在对应文档的 figures 文件夹下，Visio原图保存在 ../vsd 文件夹下。

行内标记

内联标记(inline markup)

rst通过内联标记对文本定义不同的效果，最基础的内联标记有斜体、粗体、字面量、角色等，以下进行具体说明。

斜体

斜体的表示方式：*text*，如斜体。斜体的使用包括以下情况：

宏名称
变量名称
寄存器的某个field或bit名称
...

粗体

粗体的表示方式：**text**，如粗体。粗体的使用包括以下情况：

模块或子模块名称
寄存器名称
...

字面量

字面量的表示方式：``text``，如 字面量。字面量的使用包括以下情况：

SDK路径或地址
结构体名称
...

角色/role

“角色”（role）是内联标记的一种形式，用来定义特殊的文本格式或链接，通过保证特定文本在渲染时被按照特定的样式或方式处理，来增强文档的语义和可读性。

角色的语法为 :role:`content`，以下是一些常用角色。

常用角色
角色	说明	效果
`:file:`	用于标识文件	`../../conf.py`
`:guilabel:`	用于标识图形界面元素	OK
`:menuselection:`	用于标识菜单条目	File > New > Project
`:kbd:`	用于键盘输入指令	`Ctrl+C`
`:sup:`	用于上标	Bluetooth^®
`:sub:`	用于下标	H₂O
`:mod:`	用于引用模块	`SPI`
`:func:`	用于引用函数	`print()`
`:class:`	用于引用类	`MyClass`
`:meth:`	用于引用类的方法	`MyClass.method()`
`:emphasis:`	用于强调文本（通常渲染为斜体）	文本
`:strong:`	用于表示重要的文本（通常渲染为粗体）	重要文本
`:literal:`	用于内联代码或字面值（通常渲染为等宽字体）	`代码片段`

指令标记

还有一些指令可以实现不同的行内标记效果，如：

居中加粗指令 .. centered::

创建居中加粗文本行
文档标题指令 .. rubric::

文档标题

备注

.. rubric:: 指令用来创建文档标题，但是该标题不出现在文档的目录结构，常用作脚注说明。

CSS标记 (暂不支持)

基础的行内标记不能嵌套，无法简单地实现“斜体加粗”的功能，需要借助HTML/CSS功能来实现。

块/block

以缩进为级别，整个文档可以看作时不同级别的缩进结构内容的排列与嵌套，这些不同的结构可以看作一个块（block）。

文字块

使用 :: 开头，保持同一缩进即可。

这是一个文字块
文字块中的内容与实际显示效果一样

保持相同缩进即可

这是新的一行（可以有空行，也可以不用空行，因为顶格没有缩进，该段被视为新的段落）。

注意

以下内容仅为文字块使用示例，并非实际的工程结构说明。

ameba-iot-docs-s仓库目录结构：

└── ameba-iot-docs-s                文档GitHub私有仓库名称
    └── ameba                       Ameba IC通用源文件
        ├── zh                      中文版本源文件
        └── en                      英文版本源文件
            ├── at_command          AT Command文档内容、图片
            └── software_tools      所有Software Tools文档内容、图片
    └── amebadplus                  AmebaDPlus源文件
        ├── build                   编译后生成的html文件
        ├── zh
        └── en
            ├── application_note    所有Application Note文档内容、图片
            ├── conf.py             编译html文件时使用的配置文件
            ├── index.rst           编译html文件时的入口文件
            └── index_nda.rst       编译NDA版本html文件时的入口文件
    ├── amebadlite                  AmebaLite源文件
    ├── amebadsmart                 AmebaSmart源文件
    ├── sphinx_venv                 Sphinx工程虚拟Python环境
    └── conf_common.py              Sphinx工程通用配置文件

SDK目录结构：

└── SDK                             SDK工具包
    ├── bin                         应用程序链接的二进制文件
    ├── doc                         文档
    ├── download_images             快速启动的下载images
    ├── include                     提供接口定义的头文件
    ├── samples                     配置好可直接使用的Keil实例工程
    ├── subsys                      上层和硬件无关的软件协议
    └── tools                       工具集

Peripheral示例工程结构：

└── Project: peripheral
    └── secure_only_app
        └── Device                   存放启动代码
            ├── startup_rtl.c
            └── system_rtl.c
        ├── CMSIS                    存放CMSIS文件
        ├── contribute               如何参与项目，贡献与投稿的说明
        ├── CMSE Library             Non-secure callable lib
        ├── Lib                      应用程序使用的所有二进制文件
        ├── Peripheral               应用使用的所有外设驱动和模块代码
        └── APP                      peripheral应用的实现
            ├── app_task.c
            ├── main.c
            └── peripheral_app.c

备注

文字块中的中文标点和一些特殊符号，可能在生成在线文档时报错，此时可以用 .. highlight:: rst 和 .. highlight:: none 两条指令将文字块包含，用来设定文字块的默认语法高亮方式为rst，即可消除告警。

代码块/code-block

使用 .. code-block:: 指令生成代码块。

参数释义

code-block:: language，指定代码块的语法高亮规则
emphasize-lines:: 高亮特定行
linenos:: 显示行号，默认显示在左侧单独一列
caption:: 添加代码块标题
name:: 代码引用标签

以下列出一些常用的编程语言及其对应的language标识符：

常用的编程语言：
- Python: python
- C: c
- C++: c++
- Java: java
- JavaScript: javascript
- HTML: html
- CSS: css
- JSON: json
- YAML: yaml
- Markdown: markdown
数据格式和标记语言：
- XML: xml
- SVG: svg
- LaTeX: laTeX
- reStructuredText: rst
脚本语言：
- Perl: perl
- Ruby: ruby
- PHP: php
- Lua: lua
配置文件：
- INI: ini
- Dockerfile: docker
- Makefile: make
其他：
- SQL: sql
- Diff/Patch: diff
- Matlab/Octave: matlab

以下是一段C语言代码示例：

高亮代码块示例

/* This is a sample code of C language */
#include<stdio.h>
int main()
{
   printf("%s\n","aaaa");
   return 0;
}

备注

文本代码块示例中所有参数选项都不是必须的。
代码块的引用需name，caption搭配，使用 :name: 为代码块添加引用标签，使用 :caption: 添加代码块标题，同时在引用时显示链接为高亮代码块示例

行块

行块使用 | 开头，后续文本与之保持一个空格。
这样可以保证输出的正文和原文件的排列一致。
与正文段落作区分，减少段落之间的空行。

测试块

测试块是交互式的Python会话，以 >>> 开始，一个空行结束。

>>> print "This is a doctest block."
This is a doctest block.

注释

使用 .. 开头，后续添加注释内容。

注释文本要求与文字块相同，缩进取消即为新的段落。

警告

注释文本紧跟符号 .. ，而文字块文本与 :: 有一个空白行。

分隔线

分隔线使用四个 ----，效果如下。

备注

分隔线与上下内容之间需要有空行区分。
分隔线不能紧贴在大纲标题之前或之后，也不能放在文档最开头。
两个分隔线不能紧贴，必须有除了空行之外的内容。

交叉引用/ref

交叉引用通过 .. _ref_id: 与 :ref: 的配合实现。

使用 .. _ref_id: 在引用源处添加标签名称。
使用 :ref:`ref_id` 在需要引用时添加跳转。

例如：这是交叉引用/ref，也可以自定义显示文字。

备注

整份在线文档中的标签名必须唯一，否则可能会引发错误或警告，可以采用 .. _文档名_标签: 的方式命名。
英文文档中，ref_id 全部使用小写字母，下划线连接。
:ref: 提供的是链接跳转，而不是直接引用内容。关于内容引用，请参考内容引用/include。
rst文档之间的跳转，可以使用指令 :doc:`文档名/路径` 直接跳转。
图片、表格、代码等跳转，可以在 .. table:: .. figure:: .. code-block:: 指令处添加 :name: 选项参数说明，之后可直接使用 :ref: 跳转。

内容引用/include

使用 .. include:: 指令可引用文档内容。

为了避免重复内容，实现内容同源，借助 .. include:: 指令实现内容重用非常有必要，尤其是对于维护大型文档、团队协作等情况而言。

可分为两种情况：

局部正文内容引用
整份.rst文件引用

备注

.. include:: 指令直接引用文件的内容，而非指向该文件的链接。
该指令会对内容进行解析，如果导入文件中包含rst的语法，都会被正确地解析和渲染。

以下是测试文本，供后文讲解行引用和节点引用时使用。

这是第1行
这是第2行
这是第3行
这是第4行

行引用

参数释义

include:: 引用文件，可以是当前文件，也可以添加文件路径，必须注明文件类型
start-line:: 引用开始行，不包含当前行内容
end-line:: 引用结束行，不包含当前行内容

以下是行引用的示例：

备注

整份在线文档中的标签名必须唯一，否则可能会引发错误或警告，可以采用 .. _文档名_标签: 的方式命名。
英文文档中，ref_id 全部使用小写字母，下划线连接。

小心

行引用引用的是绝对行数，有一定的使用限制，即由于内容的修改引起行数变化时，需要及时更新行数，所以不建议使用。

节点引用

参数释义

include:: 引用文件，可以是当前文件，也可以添加文件路径，必须注明文件类型
start-after:: 引用开始，添加引用开始标签
end-before:: 引用结束，添加引用结束标签

以下是节点引用的示例：

这是第1行
这是第2行
这是第3行
这是第4行

备注

:start-after: 和 :end-before: 后的标签名称必须唯一。
使用语法 .. 标签 在引用处添加标签名称。

块引用

使用 .. literalinclude:: 指令，把导入的文件内容当作“字面量”来对待，对导入的所有文本显示在文字块中，不进行再次解析。

块引用适用于引用源代码，或其他不希望被处理的文本。

备注

可以以文本的形式直接导入内容。
也可以选择高亮以及提取哪些行。

内联替换/replace

文字替换

使用 |text| 产生替换，并统一使用 .. |text| replace:: 声明替换内容。

这是替换文本，在需要使用的时候可以多处引用。

备注

在文档中涉及频繁重复的长文本或者插入常用的内容，可以使用替换标记。
替换声明在文档中不显示。
rst中有一个默认的替换字段 |release|，一般对应于 conf.py 配置文件中的 release 变量，可直接使用。

图像替换

使用 |text| 产生替换，并统一使用 .. |text| image:: 图片路径 声明替换图片。

红灯停，绿灯行。

亮了等一等（这个黄灯的图片是文字替换过来的）。

备注

图像替换与文字替换指令相同，适用于在文本中需要添加图片或者操作按钮图标的情况。
可以添加 :scale: 参数改变图像大小。

内容过滤/only

only 指令允许根据编译时的标签（tags）来有选择地包含或排除某些内容，以便创建针对不同受众或用途的文档版本。

小心

only指令包括的内容块需要缩进，否则不能正确提取。
有多个指令或多级缩进时，需要按照规则进行逐层缩进。
tags为内容过滤时的标识，在最终编译时会用到，必须书写正常。
tags一般会提前定义，请不要随意扩展，否则会导致内容提取出错。
有多个tag时，用 or``或 ``and 连接。

指令/directive

“指令”是rst中一种定义块级元素的方式，比如上述的表格、图片等都是采用指令生成，rst通过不同的指令可以丰富文档的展示效果。

指令的语法格式为 .. directive::。

指令主要包括以下几类：

强调

使用 .. 强调:: 指令生成各种强调窗口（不同的颜色。

此处的``强调``是统称，可以是以下各种强调关键字和显示格式：

使用admonition可以自定义标题

自定义标题是 .. admonition:: 指令与其他强调语法的不同之处，其余格式均相同
较短内容可以直接在指令后填写，需要和指令保持一个空格
较长的文字可以在区块上继续说明，需要保持相同缩进，不可以顶格

备注

这是note指令，显示为蓝色。

参见

这是seealso指令，显示为蓝色。

注意

这是attention指令，显示为橙色。

警告

这是warning指令，显示为橙色。

小心

这是caution指令，显示为橙色。

危险

这是danger指令，显示为红色。

错误

这是error指令，显示为红色。

提示

这是hint指令，显示为绿色。

重要

这是important指令，显示为绿色。

小技巧

这是tip指令，显示为绿色。

选项卡/tabs

使用 .. tabs:: 指令定义选项卡，子卡页面使用 .. tab:: 指令生成。

J-Link Software v6.32（或更新）版本
RTL8720E SDK
EVB Kit

在 Linux 下运行这个命令。

备注

选项卡组件对于展示不同版本的代码，或者展示同一内容的不同语言版本等情形非常有用。
可以在选项卡指令后添加分隔线，方便与正文区分。

折叠/toggle

使用 .. toggle:: 指令生成折叠，用于创建一个可折叠和展开的段落或章节。

Click to show
Clcik to hide

备注

这个功能在需要提供额外信息，但又希望初始显示时保持页面简洁的情况下非常有用。

超链接

行内超链接

使用 `显示名称 <链接地址>`_ 生成行内超链接，点击可以直接跳转。

例如：RealMCU 直接在行内显示。

多处超链接

如果在文中需要多次使用超链接，为了避免每次定义，也可以使用以下方式：

使用 .. _显示名称: 链接地址 声明超链接（一般在文末统一定义），并在需要使用时直接用 显示名称_ 即可多次引用。

百度

RealMCU

备注

.. _显示名称: 链接地址 这些链接声明不会在文档中显示。

下载/download

使用 :download: 指令提供文件下载，该指令只对 html 输出有效。

例如：图片下载：LOGO

备注

对于 .png .jpg 格式的图片，浏览器默认会直接打开图片。
对于无法直接打开的文件类型，如 .py .pdf .doc，浏览器会弹出窗口选择下载。

脚注

使用 [#name]_ 产生脚注，并使用 .. [#name] 声明脚注信息。

脚注在文中会以编号的形式输出 [1]，且格式上位于上标位置 [2]。点击文中脚注的链接可以跳转到脚注说明处，通常使用 .. rubric:: 指令置于文档或者段落末尾，之后可以点击该脚注的链接重新跳回之前文中的阅读位置。

脚注申明

备注

# 添加在脚注名称之前可以自动编号，避免序号混乱。
脚注名称不会显示，用作本地区分，HTML上仅显示标号。
脚注的定义不能放在引用之前，否则定义将无法找到。

参考

使用 [name]_ 来引用参考资料，与脚注的用法及其类似，除了除了它在文中输出的是正文格式的文本而不是上标格式的编号。如： [cit2002]

[cit2002]

添加参考资料信息

脚注和参考的语法相同，在显示上有以下差别

HTML：脚注会显示成数字上标，参考则显示与文本一致。
PDF：脚注会在页脚作注释，而参考文档信息在整篇PDF最后生成一页放置所有资料。

词汇表/glossary

使用 .. glossary:: 指令生成词汇表。

.. glossary::
   :sorted:

   SoC
      System on-Chip

备注

:sorted: 属性选项用于词汇表自动排序。