1. 介绍
在阅读 Pytorch 源代码时， 经常会看到如下的注释信息：
既不是 latex 也是不是 markdown 格式，
而阅读他们的方式是
- 在 pycharm 中，将鼠标停在该区域悬停一会而，便能出现可阅读的文本；
- 而当需要长时间阅读，或者对比其他模块时， 此时应该 到该库的官方文档中进行 查找，因为.rst 文件他们本身就是 编译成. html 格式给开发人员阅读的。
r"""The spectral modularity pooling operator from the `"Graph Clustering
with Graph Neural Networks" <https://arxiv.org/abs/2006.16904>`_ paper.
.. math::
\mathbf{X}^{\prime} &= {\mathrm{softmax}(\mathbf{S})}^{\top} \cdot
\mathbf{X}
\mathbf{A}^{\prime} &= {\mathrm{softmax}(\mathbf{S})}^{\top} \cdot
\mathbf{A} \cdot \mathrm{softmax}(\mathbf{S})
.. note::
For an example of using :class:`DMoNPooling`, see
`examples/proteins_dmon_pool.py
<https://github.com/pyg-team/pytorch_geometric/blob
/master/examples/proteins_dmon_pool.py>`_.
Args:
channels (int or List[int]): Size of each input sample. If given as a
list, will construct an MLP based on the given feature sizes.
k (int): The number of clusters.
dropout (float, optional): Dropout probability. (default: :obj:`0.0`)
"""
1.1 概念
reStructuredText是一种轻量级的文本标记语言，直译为：重构建的文本，为Python中Docutils项目的一部分。其一般保存的文件以.rst为后缀。在必要的时候，.rst文件可以被转化成PDF或者HTML格式，也可以有Sphinx转化为LaTex,man等格式，现在被广泛的用于程序的文档撰写。
reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。
.rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。
1.2 使用场景
当你写了个Python的模块，用Markdown写个个README，传到GitHub，感觉效果还不错，就难抑冲动，打了个包，也想放到PyPI上，结果放上去，发现README变成了源代码。
一查，才发现PyPI竟然不支持Markdown格式的README文件，支持的README要reStructuredText格式的。
此时需要熟系语法了。
2. 使用规则
reStructuredText大致分章节，段落，块和列表这几种内容。而在这其中reStructuredText最主要用得到的标记有以下几个：
sphinx make html :https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html
reStructuredText是一种轻量级的文本标记语言，直译为：重构建的文本，为Python中Docutils项目的一部分。其一般保存的文件以.rst为后缀。在必要的时候，.rst文件可以被转化成PDF或者HTML格式，也可以有Sphinx转化为LaTex,man等格式，现在被广泛的用于程序的文档撰写。
reStructuredText大致分章节，段落，块和列表这几种内容。而在这其中reStructuredText最主要用得到的标记有以下几个：
标题（Title）
来看看标题的实例：
怎么样，看起来不难吧，你只要按这个写法，就能被reStructuredText认识，并被解释为章节标题。reStructuredText可用于作为标题修饰的字符有很多很多：
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
只要你想，上面的任意一个都可以用来作为标题的修饰符，当然，reStructuredText也是有推荐的，它推荐下面这些字符：
= - ` : . ' " ~ ^ _ * + #
这些字符是上面一堆字符中稍微看起来不会那么奇怪的一部分，当然，个人建议不要那么花哨，尽量用这两个中的一个：
= -
上面实例的写法也许有点复杂，.rst文件中，你还可以只给出下半部分的字符即可：
TIPS：作为修饰的字符长度要大于等于文字长度。另外，标题是能够嵌套的。
段落（Paragraphs）
段落一般隶属于某个章节中，是一块左对齐并且没有其他元素体标记的块。在.rst文件中，段落和其他内容的分割是靠空行来完成，如果段落相较于其他的段落有缩进，reStructuredText会解析为引用段落，样式上有些不同。
这里是一段reStructuredText的内容，它可以很长很长。。。。最后，末尾留出空行表示是本段落的结束即可。这里是另外一段reStructuredText的内容，这段内容和上一段之间，乃至后面的其他内容之间都要留出空行进行分割。 这个也是段落，但是由于缩进了，会变成引用段落。显示和直接的段落有点不同
列表(List)
列表在HTML中被分为两种，一个是有序列表（Enumerated Lists），一种是无序列表（Bullet Lists），在reStructuredText中，我们也能找到这两种列表，还有一种称为定义列表（Definition Lists），这和HTML中的DL一样，在**.rst**文件中可以支持嵌套列表。
无序列表要求文本块是以下面这些字符开始，并且后面紧跟空格，而后跟列表项的内容，其中列表项比趋势左对齐并且有与列表对应的缩进。
* + - • ‣ ⁃
还是那句话，用最常用的几个字符就好，不用那么花哨。下面是示例：
有序列表在格式上和无序列表差不多，但是在使用的前缀修饰符上，使用的不是无序列表那种字符，而是可排序的字符，可以识别的有下面这些：
arabic numerals: 1, 2, 3, ... (no upper limit).uppercase alphabet characters: A, B, C, ..., Z.lower-case alphabet characters: a, b, c, ..., z.uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).
如果你不想使用这些，在你标明第一个条目的序号字符后，第二个开始你还可以使用”#”号来让reStructuredText自动生成需要的序号（Docutils >= 0.3.8）。
定义列表：每个定义列表项里面包含术语（term），分类器（classifiers，可选）， 定义（definition）。术语是一行文字或者短语，分类器跟在术语后面，用“ ： ”(空格，冒号，空格）分隔。定义是相对于术语缩进后的一个块。定义中可以包含多个段落或者其他的内容元素。术语和定义之间可以没有空行，但是在定义列表前后必须要有空行的存在。下面是示例：
TIPS：在reStructuredText中，还有两种列表，一种是字段列表（Field Lists），一种是选项列表（Option Lists）。由于是rst的语法入门教程，这里不做深入介绍。
表格(Table)
reStructuredText提供两种表格：网格表格（Grid Tables）， 简单表格（Simple Tables）。
网格表中，共使用的符号有：
- = | +
“-” 用来分隔行， “=“ 用来分隔表头和表体行，”|” 用来分隔列，而”+”用来表示行和列相交的节点，如下面的例子：
+------------------------+------------+----------+----------+| 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. |+------------------------+------------+---------------------+
TIPS：表头行是可选的，如果你不需要，就可以不用”=”来分割了。
简单表格：这种表格比网格表来说简单许多，一般用于简单的数据展示。其用于修饰的字符也仅两个而已：
= -
一般用”=”就能完成简单表格的绘制，如果有表头，同样需要用”=”将它和表体(body)内容分开，否则会被视为无表头数据。
`下面这种是最简单的表格形式，当然你也可以去掉表头展示。`1 Second column of row 1.2 Second column of row 2. Second line of paragraph.3 - Second column of row 3.\ Row 4; column 1 will be empty.
TIPS：列需要和”=”左对齐，不然可能会导致出错；如果碰到第一列为空时，需要使用”\”来转义，不然会被视为是上一行的延续；网格表和简单表中，简单表比较适合展现简单的数据，这些数据本身不需要太复杂的展现形式，而一旦碰到需要和并单元格这类的复杂操作，可能网格表会更加适合。
表格中还有更复杂的表格形式，比如：CSV表格，列表表格。这些复杂的格式就留给有兴趣的朋友深入吧。
块（Blocks）
块在reStructuredText中的表现方式也有好几种，但是最常见的是文字块(Literal Blocks)。这种块的表达非常简单，就是在前面内容结束之后，用两个冒号” :: “(空格[Optional]，冒号，冒号）来分割，并在之后紧接着插入空行，而后放入块的内容，块内容要相对之前的内容有缩进。
但是，当内容像这样，不再和块内容一样缩进时，块内容就自动的结束了。
这是块的最简单方式，一般我们编写的代码块就是用这种方式表现（如下）， 除此之外，.rst还有引用文字块(Quoted Literal Blocks)，行块（Line Blocks），块引用（Block Quotes）等。
更多的块内容，请参阅官方帮助文档。
样式(Style)
reStructuredText中支持对文本进行样式控制，比如：粗体(Strong)，斜体(Italic)，等宽字体(Monospace)，引用( interpreted text)。
This is **Strong Text**. HTML tag is strong.粗体This is *Emphasis* Text.这个HTML使用em， 斜体This is `Interpreted Text`. 注意，这个HTML一般用<cite>表示This is ``Inline Literals``. HTML tag is <tt>. 等宽字体.
来点补充，如果你需要在文档中插入超链接，那么你可以像下面这样：
.. _链接: http://blog.useasp.net
这种方式要求定义链接，而后引用链接。而且链接要有空格分隔前面的文字。这种方式略嫌麻烦，你可以用更加简化的方式——个人比较推荐：
这里同样是一个 `链接<http://blog.useasp.net>`_，不需要特别设置。
TIPS： 我们会发现，两个处理连接的时候，都需要在链接文字前面要空格与前面进行分割，这个在英文当中比较好处理，因为单个词之间有空格，而在中文中，字之间没有空格，如果加入空格，在显示时会有空格，影响观感，为此，如果在中文中使用，需要考虑好。
reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。
.rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。
本文语法来自Quick reStructuredText
由于格式原因，觉得这个不是很直观的话，可以到我的github上查看。
行内样式
斜体
重点、解释文字
`解释文字(interpreted text)通常显示为斜体`
重点(emphasis)通常显示为斜体
粗体
重点强调
**重点强调(strong emphasis)通常显示为粗体**
重点强调(strong emphasis)通常显示为粗体
等宽
``行内文本(inline literal)通常显示为等宽文本，空格可以保留，但是换行不可以。``
行内文本(inline literal)通常显示为等宽文本，空格可以保留，但是换行不可以。
章节标题
章节头部由下线(也可有上线)和包含标点的标题 组合创建, 其中下线要至少等于标准文本的长度。
可以表示标题的符号有 =、-、`、:、'、"、~、^、_ 、***** 、+、 #、<、> 。
对于相同的符号，有上标是一级标题，没有上标是二级标题。
标题最多分六级，可以自由组合使用。
全加上上标或者是全不加上标，使用不同的 6 个符号的标题依次排列，则会依次生成的标题为H1-H6。
一级标题
二级标题
一级标题
二级标题
三级标题
四级标题
五级标题
六级标题
段落
段落是被空行分割的文字片段，左侧必须对齐（没有空格，或者有相同多的空格）。
缩进的段落被视为引文。
列表
符号列表(Bullet Lists)
符号列表可以使用 -、 *、+ 来表示。
不同的符号结尾需要加上空行，下级列表需要有空格缩进。
-
符号列表1
-
符号列表2
-
二级符号列表1
-
二级符号列表2
-
二级符号列表3
-
-
符号列表3
-
符号列表4
枚举(顺序)列表(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
- 枚举列表2
- 枚举列表3
I. 枚举列表1
II. 枚举列表2
III. 枚举列表3
A. 枚举列表1
B. 枚举列表2
C. 枚举列表3
定义列表(Definition Lists)
定义列表可以理解为解释列表，即名词解释。
条目占一行，解释文本要有缩进；多层可根据缩进实现。
定义1
这是定义1的内容
定义2
这是定义2的内容
字段列表(Field Lists)
:标题: reStructuredText语法说明
标题: reStructuredText语法说明
作者:
- Seay
- Seay1
- Seay2
时间: 2016年06月21日
概述: 这是一篇 关于reStructuredText
语法说明。
选项列表(Option Lists)
选项列表是一个类似两列的表格，左边是参数，右边是描述信息。当参数选项过长时，参数选项和描述信息各占一行。
选项与参数之间有一个空格，参数选项与描述信息之间至少有两个空格。
-a command-line option "a"-b file options can have arguments--long options can be long also--input=file long options can also have/V DOS/VMS-style options too
| 参数选项 | 描述信息 |
|---|---|
| -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 |
由于格式问题，这里只是一个示例，实际上时没有上面的表头列和表格竖直线的。
块(Blocks)
文字块(Literal Blocks)
文字块就是一段文字信息，在需要插入文本块的段落后面加上 ::，接着一个空行，然后就是文字块了。
文字块不能定顶头写，要有缩进，结束标志是，新的一段文本贴开头，即没有缩进。
下面是文字块内容：
这是新的一段。
行块(Line Blocks)
行块对于地址、诗句以及无装饰列表是非常有用的。行块是以 | 开头，每一个行块可以是多段文本。
| 前后各有一个空格。
下面是行块内容：
这是新的一段。
块引用(Block Quotes)
块引用是通过缩进来实现的，引用块要在前面的段落基础上缩进。
通常引用结尾会加上出处(attribution)，出处的文字块开头是 –、— 、—，后面加上出处信息。
块引用可以使用空的注释 … 分隔上下的块引用。
注意在新的块和出处都要添加一个空行。
“真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。”
下面是引用的内容：
“真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。”
文档测试块(Doctest Blocks)
文档测试块是交互式的Python会话，以 >>> 开始，一个空行结束。
>>> print "This is a doctest block."
>>> print "This is a doctest block."
表格(Tables)
reStructuredText提供两种表格：网格表（Grid Tables），简单表（Simple Tables）。
网格表(Grid Tables)
网格表中使用的符号有：-、=、|、+。
- 用来分隔行， = 用来分隔表头和表体行，| 用来分隔列，+ 用来表示行和列相交的节点。
+------------+------------+-----------+| 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. |+------------+------------+-----------+
效果请查看:这里
简单表(Simple Tables)
简单表相对于网格表，少了 | 和 + 两个符号，只用 - 和 = 表示。
效果请查看:这里
分隔符
分隔符就是一条水平的横线，是由 4 个 - 或者更多组成，需要添加换行。
上面部分
下面部分
超链接
介绍各类带有链接性质的超链接
自动超链接
reStructuredText会自动将网址生成超链接。
https://github.com/SeayXu/
外部超链接(External Hyperlink)
引用/参考(reference)，是简单的形式，只能是一个词语，引用的文字不能带有空格。
这篇文章来自我的Github,请参考 reference_。.. _reference: https://github.com/SeayXu/
引用/参考(reference)，行内形式，引用的文字可以带有空格或者符号。
这篇文章来自我的Github,请参考 `SeayXu <https://github.com/SeayXu/>`_。
内部超链接|锚点(Internal Hyperlink)
这里是其他内容
这是引用部分的内容
匿名超链接(Anonymous hyperlink)
词组(短语)引用/参考(phrase reference)，引用的文字可以带有空格或者符号，需要使用反引号引起来。
间接超链接(Indirect Hyperlink)
间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名_。
隐式超链接(Implicit Hyperlink)
小节标题、脚注和引用参考会自动生成超链接地址，使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。
第一节 介绍
其他内容…
隐式链接到 第一节 介绍，即可生成超链接。
替换引用(Substitution Reference)
替换引用就是用定义的指令替换对应的文字或图片，和内置指令(inline directives)类似。
这是 |logo| github的Logo，我的github用户名是:|name|。.. |logo| image:: https://help.github.com/assets/images/site/favicon.ico.. |name| replace:: SeayXu
脚注引用(Footnote Reference)
脚注引用，有这几个方式：有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。
手工序号可以和#结合使用，会自动延续手工的序号。
# 表示的方法可以在后面加上一个名称，这个名称就会生成一个链接。
脚注引用一 [1]
脚注引用二 [3]
脚注引用三 [4]
脚注引用四 [*]
脚注引用五 [†]
脚注引用六 [‡]
[1] 脚注内容一
[2] 脚注内容二
[3] 脚注内容三
[4] 脚注内容四 链接
[*] 脚注内容五
[†] 脚注内容六
[‡] 脚注内容七
引用参考(Citation Reference)
引用参考与上面的脚注有点类似。
引用参考的内容通常放在页面结尾处，比如 [One]_，Two_
[One] 参考引用一
[Two] 参考引用二
注释(Comments)
注释以 … 开头，后面接注释内容即可，可以是多行内容，多行时每行开头要加一个空格。
本文作为学习笔记，如有侵权，请联系删除
ref
https://blog.csdn.net/zhangxinrun/article/details/49926919
https://blog.csdn.net/liuskyter/article/details/86570790
https://blog.csdn.net/u012150179/article/details/37743605
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
