2. reStructuredText 标记规范

reStructuredText 是一个使用简单且直觉化的构造来表述文档结构的标记语言。 这些结构既易读易写又容易处理。这篇文档自己就是 reStructuredText 的一个例子。 reStructuredText 的解析器是 docutils 的一个组件。

简单的隐式标记被轧来表述特殊构造，例如章节标题、项目列表、强调等等。 使用的标记尽可能地最小且不引人注意。基本的 reStructuredText 尽量使用较少的构造而扩展使用更复杂的显式标记。

reStructuredText 适用于任意长度的文档，从非常短（嵌入式的文档片段）到非常大（如本文档）。

第一个章节给出了一个快速总览，完整的规范在 语法描述 章节给出。

字面块（不会解析标记）被用来展示例子，表明标记的纯文本形式。

2.1. 总览

一篇 reStructuredText 文档是由体或块级元素组成的，并可以使用章节来组织。 `章节标题`_ 可以使用下划线或可选的上划线风格标记。章节可以包含 body 与子章节。 一些体元素可以包含进一步的元素，例如列表包含列表，列表包含段落或其他块元素等等。 作为一个段落，可以包含文本与 `行内标记`_ 元素。

这里有一些体元素的例子：

段落与行内标记

段落包含文本与行内标记：*着重*，**更着重**，`解释型文本`，``行内字面量``，
独立超链接（https://www.python.org），外部超链接（Python_），交叉引用（example_），
脚注（[#1]_），引文引用（[CIT2002]_），替换引用（|example|），以及行内链接目标
_`inline iternal targets`。

段落使用空行划分，左对齐。

几种列表

无序列表

-   这是无序列表，使用项目符号做前缀，每一条项目跟在后面
-   项目符号可以使用 ``*``, ``+`` 或 ``-``

有序列表

1.  这是有序列表
2.  有序列表可以使用数字、字母或罗马数字为前缀
#.  也可以使用 ``#`` 符号让之后的编号自动推导

定义列表

这是什么
    定义列表将术语与它的定义联系起来。

如何编写
    术语是一个单行文本，定义则是紧跟在其后的一个或多个段落或其他体元素。
    定义需要比术语多一个缩进。

字段列表

:啥: 字段列表将字段名映射为字段体，就像数据库记录一样，通常作为扩展语法的一部分。

:怎样: 字段名标记是一个冒号+字段名+冒号

    字段体可以是一个或多个体元素，第一个体元素可以跟在字段名后面，多余的需要比字段名多一个缩进。

选项列表

主要用来列出一个命令行程序的命令行选项:

-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

选项和它的帮助信息之间需要至少有两个空格的间隔。

字面量块

字面量块是一个缩进或行前缀引言的块，在前一个段落的末尾需要有一个双冒号 ``::``
（就像这样 -->）::

    printf("%s", "Hello World!");

块引言

块引言由一个缩进的块元素组成：

    Everyone will going to die, but several of them need a little help.

        -- Lucian

文档测试块

专门用于 Python，执行文档测试:

>>> print("Hello World!")
Hello World

两种表格语法

网格表格

完整，但复杂而详细:

+------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

简单表格

小而紧凑，但是受限:

====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

显式标记块

都以一个显式标记块符号（两个点加一个空格）开始：

脚注:

.. [1] 一个脚注由标签和一个或多个体元素组成。
    标签可以是纯数字或一个井号后接文字（``[#fn-example]``）。

    标签的引用需要在标签后加一个下划线： ``[1]_``，渲染出的效果和标签内容无关，而是自动编号。

    另外的体元素一贯地需要缩进一次。

引文:

.. [CIT2002] 和脚注一样，除了标签是文字的。引用处的标签也是文字。

超链接目标:

.. _Python: https://www.python.org/

.. _example:

    上面的 _Python 将会引向一处网址，而 _example 则是此段落。

指令（Directive）:

.. image:: img/59498721_p0.jpg

替换定义:

.. |替换| replace:: 文本

注释:

.. 任何不满足标记规则的显式标记块都是注释，不会出现在输出中。

以下是上述例子的渲染效果：

---

段落包含文本与行内标记：着重，更着重，解释型文本，行内字面量， 独立超链接（https://www.python.org），外部超链接（Python），交叉引用（example）， 脚注（[1]），引文引用（[CIT2002]），替换引用（文本），以及行内链接目标 inline iternal targets。

段落使用空行划分，左对齐。

• 这是无序列表，使用项目符号做前缀，每一条项目跟在后面
• 项目符号可以使用 *, + 或 -

1. 这是有序列表
2. 有序列表可以使用数字、字母或罗马数字为前缀
3. 也可以使用 # 符号让之后的编号自动推导

这是什么

定义列表将术语与它的定义联系起来。

如何编写

术语是一个单行文本，定义则是紧跟在其后的一个或多个段落或其他体元素。 定义需要比术语多一个缩进。

啥:

字段列表将字段名映射为字段体，就像数据库记录一样，通常作为扩展语法的一部分。

怎样:

字段名标记是一个冒号+字段名+冒号

字段体可以是一个或多个体元素，第一个体元素可以跟在字段名后面，多余的需要比字段名多一个缩进。

-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

字面量块是一个缩进或行前缀引言的块，在前一个段落的末尾需要有一个双冒号 :: （就像这样 –>）:

printf("%s", "Hello World!");

块引言由一个缩进的块元素组成：

Everyone will going to die, but several of them need a little help.

– Lucian

>>> print("Hello World!")
Hello World

Header row, column 1	Header 2	Header 3
body row 1, column 1	column 2	column 3
body row 2	Cells may span

Header row, column 1	Header 2	Header 3
body row 1, column 1	column 2	column 3
body row 2	Cells may span columns

[1]	一个脚注由标签和一个或多个体元素组成。 标签可以是纯数字或一个井号后接文字（[#fn-example]）。 标签的引用需要在标签后加一个下划线： [1]_，渲染出的效果和标签内容无关，而是自动编号。 另外的体元素一贯地需要缩进一次。

[CIT2002]

和脚注一样，除了标签是文字的。引用处的标签也是文字。

上面的 _Python 将会引向一处网址，而 _example 则是此段落。

2.2. 语法描述

下面的描述列出了与语法构造相对应的 “doctree元素” （文档树元素名称； XML DTD通用标识符）。 有关元素层次结构的详细信息，请参阅 Docutils文档树 和 `Docutils通用DTD XML文档类型定义<https://docutils.sourceforge.io/docs/ref/docutils.dtd>`__。