reStructuredText¶

1 reStructuredText¶

https://docutils.sourceforge.io/rst.html
https://learn-rst.readthedocs.io/zh_CN/latest/index.html
https://ebf-contribute-guide.readthedocs.io/zh_CN/latest/index.html
reStructuredText指令
https://pandemic-overview.readthedocs.io/en/latest/myGuides/reStructuredText-Paragraphs.html

实事求是的说 Markdown 语法比 reStructuredText 语法简洁很多。

1.1 统一性¶

Markdown 有大量的衍生版，它们都支持最基本的 Markdown 语法，但又各自有所扩展。主要的衍生版有： CommonMark 、 GitHub Flavored Markdown (GFM) 、 Markdown Extra 、 MultiMarkdown 、 Pandoc Markdown 。各种衍生版的语法有一部分是互不兼容的。由于技术原因和历史原因，短期内 Markdown 世界是无法统一的。

reStructuredText 不存在这个问题，到目前为止， reStructuredText 只有一个规范和一个活跃的规范实现 — docutils 。

1.2 扩展性¶

Markdown 衍生版众多的原因是它的核心设计没有考虑可扩展机制。当一个新的需求来临时，必须修改解析器，因此才有了现在这么多的 Markdown 孤岛。相反， reStructuredText 可通过 role 和 directive 进行扩展。通过注册，就能将扩展的功能添加到 reStructuredText ，并且reStructuredText 的核心能够以一致的方式调用扩展模块的代码。文档系统 Sphinx 和静态网页生成器 Pelican 就是利用这种扩展机制实现的。

2 语法¶

2.1 标题¶

title: 标题级别划分规则
标题级别不是以**标记符类别或者标记符数量**来区分的，它是以标题**标记符出现的顺序**来划分标题级别的。如首次使用`#`符号标记标题，则`#`符号将作为一级标题，后面再次使用`#`符号标记标题将永远是一级标题。接着使用了`=`符号标记标题，那么这个`=`将永远作为第二级标题，以此类推。

可用的标记符：

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

常用的标记符：

= - ` : . ' " ~ ^ _ * + #

标题标记符数量有 2 中形式： 1. 一种标题前后都用标记符包裹 2. 一种只在标题后包裹

===============
 Section Title
===============

---------------
 Section Title
---------------

Section Title
=============

Section Title
-------------

标记符的数量一定要和标题数量相同，如果是中文，一个中文用 2 个标记符，如：以下标题4 个中文需要 8 个标记符

一级标题
--------

2.2 段落¶

一个段落就是一段用空行与其他结构进行分隔的文本区域。在一个段落中，可以用换行来划分不同的部分，只要它们中间没有产生空行就会被解析为同一个段落。

这是一个段落，有点短。
新的一行具有相同缩进，那么这两句是同一段。

上面是一个空行，这是一个新的段落。

2.3 分割线¶

任意 4 个以上的标记符表示分割线（markdown 是 3 个以上）。

title
#####
一段话

----

又一段话

2.4 内联标记¶

这些内联标记实际上是各种role，详见下面示例。

斜体：*斜体*
加粗：**加粗**
解释性文本：
字面量：通常用于包裹特殊符号

*着重*，:emphasis:`着重`
**强调**，:strong:`强调`
`解释性文本`
``字面量``，:literal:`字面量`

2.5 列表¶

有三种风格来表示一列项目，分别是无序列表、有序列表、定义列表。无序列表用 *, -, + 做项目符号，有序列表可以用数字、字母、罗马数字加上点（.）、右英文括号（)）或用英文括号完全包围 – 无论你偏好什么，都能识别:

*   无序 1

-   无序 2

+   无序 3

1.  有序 1

2)  有序 2)

(3) 有序 (3)

i.  有序 一

II.  有序 贰

c.  有序 three

嵌套列表使用缩进即可。

2.5.1 定义列表¶

与其他两个不同，定义列表由一个术语和该术语的定义组成。定义列表的格式为：

what
  Definition lists associate a term with a definition.

*how*
  The term is a one-line phrase, and the definition is one or more
  paragraphs or body elements, indented relative to the term.
  Blank lines are not allowed between term and definition.

定义以缩进表示，结束要间隔一空行。

2.6 超链接¶

reStructuredText 一个超链接需要有两个部分：引用和靶标:

引用部分需要在名称后加下划线：链接_
如果名称中包含了空格，则需要用反引号包括起来：`链 接`_。

靶标部分的下划线在名称前面：

.. _链接: https://docutils.sourceforge.io/docs/user/rst/quickref.html

如果留空，则会将靶标引至下一个块元素。

引用和靶标也可以写在同一处:

`名称 <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__

即 `name <target>`_ 的形式。前者将会渲染为显示名称，后者将会作为靶标。

靶标也有内联形式，例如:

_`靶标` 在这里，而引用将会引至前面的 靶标_ 处。

隐式超链接可以将引用引至标题:

正如下面的 `标题`_ 章节所说一样。

任何满足 Uri 形式的文本会在渲染流程的最后被识别为超链接:

-   https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets
-   ftp://firefox.fake-mozilla.org/

2.7 图片¶

2.7.1 image¶

示例：

.. image:: ../media/rest-syntax/pic-video/logo.png
   :align: center
   :alt: 野火logo

2.7.2 figure 插图¶

示例：

.. figure: ../media/rest-syntax/pic-video/logo.png
   :alt: 野火logo
   :align: center
   :caption: 野火logo

2.8 视频¶

直接使用 raw 指令再插入原生 html 语句。

.. raw:: html

<iframe height=498 width=510 src='http://player.youku.com/embed/XMzk2MzQxNTQ3Ng==' frameborder=0 'allowfullscreen'></iframe>

2.9 代码块¶

2.9.1 code-block 或者 code¶

2 个点号
一个空格
指令名称 code 或者 code-block
2 个冒号
一个空格
一个语言名称（c、sh、python 等）语法如下：

.. code-block:: c

    int main()
    {
        printf("hello world!");
    }

.. code:: c

    int main()
    {
        printf("hello world!");
    }

2.10 表格¶

2.10.1 table¶

.. table:: Truth table for "not"
   :widths: auto

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

2.10.2 csv-table¶

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

2.10.3 list-table¶

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

2.11 指令 directive¶

https://docutils.sourceforge.io/docs/ref/rst/directives.html 语法格式如下：

.. directive名:: 参数
   :参数:
   :参数:

2.11.1 Admonitions¶

特殊提示支持警告、重要、提示、注意等标签，适合做显眼的用途。支持如下： - 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.

2.12 角色 role¶

https://docutils.sourceforge.io/docs/ref/rst/roles.html 语法格式如下：

:role名: 内容