.rst 语法+简明教程

2023-05-16

reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

reStructuredText入门

reStructuredText简明教程

一、行内样式

单星号： text 强调 (斜体),
双星号： text 重点强调 (粗体)，以及
反引号： ``text`` 代码示例。

1. 子体

斜体: * ss *
粗体: ** ssss **
等宽 `` 行内文本(inline literal)通常显示为等宽文本，空格可以保留，但是换行不可以 ``

2. 章节标题

章节头部由下线(也可有上线)和包含标点的标题组合创建, 其中下线要至少等于标准文本的长度。
可以表示标题的符号有 =、-、`、:、’、"、~、^、_ 、* 、+、 #、<、> 。
对于相同的符号，有上标是一级标题，没有上标是二级标题。
标题最多分六级，可以自由组合使用。
全加上上标或者是全不加上标，使用不同的 6 个符号的标题依次排列，则会依次生成的标题为H1-H6。

=========
一级标题
=========
二级标题
=========

一级标题
^^^^^^^^
二级标题
---------
三级标题
>>>>>>>>>
四级标题
:::::::::
五级标题
'''''''''
六级标题
""""""""

3.段落

段落是被空行分割的文字片段，左侧必须对齐（没有空格，或者有相同多的空格）。
缩进的段落被视为引文。

4. 列表

4.1 符号列表(Bullet Lists)

符号列表可以使用 -、 *、+ 来表示。
不同的符号结尾需要加上空行，下级列表需要有空格缩进。

- 符号列表1
- 符号列表2

  + 二级符号列表1

  - 二级符号列表2

  * 二级符号列表3

* 符号列表3

+ 符号列表4

4.2 枚举(顺序)列表(Enumerated Lists)

枚举列表算即顺序(序号)列表，可以使用不同的枚举序号来表示列表。

可以使用的枚举有：

阿拉伯数字: 1, 2, 3, ... (无上限)。
大写字母: A-Z。
小写字母: a-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)"。
枚举列表可以结合 # 自动生成枚举序号。
1. 枚举列表1
#. 枚举列表2
#. 枚举列表3

(I) 枚举列表1
(#) 枚举列表2
(#) 枚举列表3

A) 枚举列表1
#) 枚举列表2
#) 枚举列表3


枚举列表1
枚举列表2
枚举列表3

I. 枚举列表1
II. 枚举列表2
III. 枚举列表3
A. 枚举列表1
B. 枚举列表2
C. 枚举列表3

4.3 定义列表(Definition Lists)

定义列表可以理解为解释列表，即名词解释。
条目占一行，解释文本要有缩进；多层可根据缩进实现。

定义1
 这是定义1的内容

定义2
 这是定义2的内容

定义1
这是定义1的内容  

定义2
这是定义2的内容

4.4 字段列表(Field Lists)

:标题: reStructuredText语法说明

:作者:
 - Seay
 - Seay1
 - Seay2

:时间: 2016年06月21日

:概述: 这是一篇
 关于reStructuredText

 语法说明。

标题: reStructuredText语法说明
作者:

Seay
Seay1
Seay2

4.5 选项列表(Option Lists)

选项列表是一个类似两列的表格，左边是参数，右边是描述信息。当参数选项过长时，参数选项和描述信息各占一行。
选项与参数之间有一个空格，参数选项与描述信息之间至少有两个空格。

-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

二、超链接

1. 超链接

介绍各类带有链接性质的超链接

1.1 自动超链接

reStructuredText会自动将网址生成超链接。

https://github.com/SeayXu/

https://github.com/SeayXu/

1.2 外部超链接(External Hyperlink)

引用/参考(reference)，是简单的形式，只能是一个词语，引用的文字不能带有空格。
这篇文章来自我的Github,请参考 reference_。

.. _reference: https://mp.csdn.net/mdeditor/100424467

引用/参考(reference)，行内形式，引用的文字可以带有空格或者符号。
这篇文章来自我的Github,请参考

`mayun<https://mp.csdn.net/mdeditor/100424467>`_。

这篇文章来自我的Github,请参考 mayun。

1.3 内部超链接|锚点(Internal Hyperlink)

更多信息参考 引用文档_

这里是其他内容

.. _引用文档:

这是引用部分的内容

更多信息参考引用文档
这里是其他内容

这是引用部分的内容

1.4匿名超链接(Anonymous hyperlink)

词组(短语)引用/参考(phrase reference)，引用的文字可以带有空格或者符号，需要使用反引号引起来。

这篇文章参考的是：`Quick reStructuredText`__。
.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html

这篇文章来自我的Github,请参考 Quick reStructuredText。

1.5 间接超链接(Indirect Hyperlink)

间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名_。

SeayXu_ 是 `我的 GitHub 用户名`__。

.. _SeayXu: https://github.com/SeayXu/

__ SeayXu_

SeayXu 是我的 GitHub 用户名。

1.6 隐式超链接(Implicit Hyperlink)

小节标题、脚注和引用参考会自动生成超链接地址，使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。

第一节 介绍
===========

其他内容...

隐式链接到 `第一节 介绍`_，即可生成超链接。

<h6 id="id2">第一节 介绍</h6>
其他内容...
隐式链接到 第一节 介绍，即可生成超链接。

2. 替换引用(Substitution Reference)

替换引用就是用定义的指令替换对应的文字或图片，和内置指令(inline directives)类似。

|build| |docs| |license|
.. |build| image:: https://travis-ci.org/googlecartographer/cartographer_ros.svg?branch=master
    :alt: Build Status
    :scale: 100%
    :target: https://travis-ci.org/googlecartographer/cartographer_ros

3.脚注引用(Footnote Reference)

可以使用 [#name]_ 标注在脚注的位置，在文档的最后的 … rubric:: Footnotes 后添加脚注的内容，像这样:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

脚注引用，有这几个方式：有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。

手工序号可以和#结合使用，会自动延续手工的序号。

#表示的方法可以在后面加上一个名称，这个名称就会生成一个链接。

脚注引用一 [1]_
脚注引用二 [#]_
脚注引用三 [#链接]_
脚注引用四 [*]_
脚注引用五 [*]_
脚注引用六 [*]_

.. [1] 脚注内容一
.. [2] 脚注内容二
.. [#] 脚注内容三
.. [#链接] 脚注内容四 链接_
.. [*] 脚注内容五
.. [*] 脚注内容六
.. [*] 脚注内容七

脚注引用一 [1]<a id="id9"></a>
脚注引用二 [3]<a id="id10"></a>
脚注引用三 [4]<a id="id11"></a>
脚注引用四 [*]<a id="id12"></a>
脚注引用五 [†]<a id="id13"></a>
脚注引用六 [‡]<a id="id14"></a>
[1]<a id="id3"></a> 脚注内容一
[2]  脚注内容二
[3]<a id="id4"></a> 脚注内容三
[4]<a id="id5"></a> 脚注内容四 链接  
[*]<a id="id6"></a> 脚注内容五
[†]<a id="id7"></a> 脚注内容六
[‡]<a id="id8"></a> 脚注内容七

3. 嵌入程序代码+注释

注释以 … 开头，后面接注释内容即可，可以是多行内容，多行时每行开头要加一个空格。

..
 我是注释内容
 你们看不到我

3.1 嵌入式代码

如果需要嵌入大段的程序代码(SQL, 业务逻辑设置, 配置文件等), 在段落末尾添加两个’:’. 代码的左侧必须缩进, 代码引用到没有缩进的行为止. 例如:

如果数据库有问题, 执行下面的 SQL::

 # Dumping data for table `item_table`

 INSERT INTO item_table VALUES (
   0000000001, 0, 'Manual', '', '0.18.0',
   'This is the manual for Mantis version 0.18.0.\r\n\r\nThe Mantis manual is modeled after the [url=http://www.php.net/manual/en/]PHP Manual[/url]. It is authored via the \\"manual\\" module in Mantis CVS.  You can always view/download the latest version of this manual from [url=http://mantisbt.sourceforge.net/manual/]here[/url].',
   '', 1, 1, 20030811192655);

如果没有合适的段落添加 ::, 也可以在一个空行上添加, 这个双冒号行被忽略:

::

#
# Dumping data for table `item_table`
#

INSERT INTO item_table VALUES (
  0000000001, 0, 'Manual', '', '0.18.0',
  'This is the manual for Mantis version 0.18.0.\r\n\r\nThe Mantis manual is modeled after the [url=http://www.php.net/manual/en/]PHP Manual[/url]. It is authored via the \\"manual\\" module in Mantis CVS.  You can always view/download the latest version of this manual from [url=http://mantisbt.sourceforge.net/manual/]here[/url].',
  '', 1, 1, 20030811192655);

可以用 code-block:: 追加各种语法高亮声明:

.. code-block:: python
    :linenos:

    def foo():
        print "Love Python, Love FreeDome"
        print "E文标点,.0123456789,中文标点,. "

4. 表格

普通表格

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

简单表格
注意: 表格包含中文时,基本无法对齐,

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

CSV 表格

.. 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!"

列表表格

.. 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!

5 排版

5.1跨章节指引

行文中,经常要对其它章节进行指引,在 html 中对应的就是锚点链接
rST 中提供了非常优雅的解决:
使用通用元素定义
比如説:

各个章节的首页一般是 index.rst
头一行,习惯性加个聲明:
.. _chapter6index:

那么,在其它任意文本中,随时可以使用:
:ref:`构建 buzz <chapter6index>`
来生成一个指向第二章 首页的链接!

5.2插图/表格指代

行文中,经常对指定插图/表格进行指代
rST 中提供了非常优雅的解决:
进行通用元素定义
比如说

.. _fig_0601:
.. figure:: ../_static/figs/magic-2.png

   插图 6-1 神奇的2

然后,就可以在任意地方使用插图 6-1 神奇的2 来指代, 实际输出的就是 “插图 6-1 神奇的2”

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)