reStructuredText 语法¶
| 作者: | kiki |
|---|---|
| 日期: | 2019/11/1 |
目录
章节¶
章节标题使用下划线(上划线可选)，且符号的长度不能小于文本长度。
章节标题的等级从高到底可划分(参考 https://pandoc.org/try/?text=&from=markdown&to=rst 划分)：
=小章节-子章节~子章节的子章节^子章节的子章节的子章节'子章节的子章节的子章节的子章节"段落
内联标记¶
角色¶
角色是一个显式标记的内联片。它标志着被包围的文本应该按照特定方式解释。Sphinx 使用这种方式提供语义标记及交叉索引。
语法 :rolename:`content`。Docutils 支持以下角色:
* :emphasis:`text` 等价于 *text*
* :strong:`text` 等价于 **text**
* :literal:`text` 等价于 ``text``
* :subscript:`text` 下标
* :superscript:`text` 上标
* :title-reference:`text` 用于书、期刊等的标题
链接¶
外部链接¶
文字链接：使用
`链接文本 <链接地址>`_插入网页链接。如 链接 1。自动链接：链接文本是网址或电子邮件信箱时，使用
`<链接地址>`_。如 https://mail.google.com/mail/u/0/。把链接和标签分开。这是建议的用法。便于改善文章的易读性，也可以避免重复写链接地址。如:
这里是 `链接 2`_。链接文本包含空格使用反引号包围。 中间包含一些文本段落。 这里是 `链接 3`_。和 “链接 2” 指向同一个位置。 这里是 间接链接1_。链接文本不包含空格，可以去掉反引号。链接到 “链接 2”。 这里是 间接链接2_。链接到 “间接链接1”。 .. _间接链接2: 间接链接1_ .. _间接链接1: `链接 2`_ .. _链接 2: .. _链接 3: https://cn.bing.com/
生成:
列表与引用块¶
有序列表¶
使用编号:
1. 使用编号的有序列表
2. 使用编号的有序列表
- 使用编号的有序列表
- 使用编号的有序列表
或者使用井号 #. 自动加序号:
#. 使用井号的有序列表
#. 使用井号的有序列表
- 使用井号的有序列表
- 使用井号的有序列表
嵌套列表¶
列表可以嵌套，但是需要用空行分隔子列表和父列表:
* 这是父列表
* 这也是父列表
* 这是子列表
* 这也是子列表
* 这还是父列表
- 这是父列表
- 这也是父列表
- 这是子列表
- 这也是子列表
- 这还是父列表
定义列表¶
和其他两个列表不同，定义列表主要由术语和术语的定义组成。一个定义列表的格式如下:
术语 1
定义 1。
*术语 2*
定义 2， 段落 1。
定义 2， 段落 2。
生成:
- 术语 1
- 定义 1。
- 术语 2
定义 2， 段落 1。
定义 2， 段落 2。
注意 术语不能超过一行文本。
定义列表可用于多个方面，包含:
- 作为字典或词汇表。
- 描述程序变量。
表格¶
网格表格¶
可自定义表格的边框:
+------------------------+------------+----------+----------+
| 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. |
+------------------------+------------+---------------------+
图像¶
图像指令代码如下:
.. image:: image_name
选项
其中，image_name 必须是图像的相对路径。或者以源目录为根目录的绝对路径。选项指的是图像的大小(width 和 height)、对齐等。
Sphinx 自动将图像文件拷贝到输出目录的子目录，输出 HTML 时目录为 _static。如:
.. image:: /syntax/ref/natsume.jpg
生成:
脚注¶
使用 [#标签]_ 标记脚注的位置，然后在文档末尾的 “Footnotes” 标题之后增加脚注文档。标签可以是:
- 包含一个或多个数字的十进制数字。即手动编号。
- 一个
#，这是自动编号。从1开始编号。- 一个
#后跟一个简单的引用名，即自动编号的标签。- 一个
*，这是 自动使用符号
脚注自动编号时顺序依赖于脚注的定义先后，而不是引用脚注的先后。因此注意引用自动编号的脚注时要和定义的顺序保持一致。
也可以显式给脚注编号 [1]_ 或者使用自动编号脚注 [#]_。混合使用时，手动编号优先级更高。只有未使用的脚注编号可以被赋值给自动编号的脚注。
当不能获取正确的编号时，编译会报警告信息。
像这样:
这里引用了命名脚注的文章 [#f1]_。这里引用了命名脚注的文章 [#f2]_。
这里引用了手动编号的脚注文章 [3]_。这里引用了自动编号的脚注文章 [#]_。
这里引用了手动编号的脚注文章 [4]_。这里引用了自动编号的脚注文章 [#]_。
这里引用了命名脚注的文章 [#f3]_。自动编号的标签还可以使用链接 f3_。
.. rubric:: Footnotes
.. [#f1] 第 1 个脚注的文本
.. [#f2] 第 2 个脚注的文本
.. [#f3] 第 5 个脚注的文本
.. [3] 第 3 个脚注的文本
.. [4] 第 4 个脚注的文本
.. [#] 第 6 个脚注的文本
.. [#] 第 7 个脚注的文本
生成:
引用¶
支持标准的 reST 引用，并增加了 “global” 特性。比如，所有的引用可从所有的文件链接。像这样使用:
阅读莎士比亚的 [Hamlet]_。
.. [Hamlet] 书籍、或参考文章、URL 等。
生成:
引用类似于脚注的用法，但是标签不能是数字，也不能以 # 开头。
替换¶
reST 支持替换，即在文本中通过 |name| 链接的一段文本和/或标记。使用带显式的标记块，仿照脚注定义替换。像这样:
.. |name| replace:: 替换文本
或者像这样:
.. |caution| image:: warning.png
:alt: Warning!
比如:
The |biohazard| symbol must be used on containers used to
dispose of medical waste.
.. |biohazard| image:: images/biohazard.png
生成:
Thesymbol must be used on containers used to dispose of medical waste.