3. reStructuredText(reST)语法示例¶
详细的用法可以参考:
- reStructuredText Primer
- Quick reStructuredText
- ReStructuredText介绍
- reStructuredText 简介
- reStructuredText标记规范
- reStructuredText入门
- reStructuredText-Quick-Syntax
3.1. 文本样式¶
* 斜体： *斜体*
* 粗体： **粗体**
* 行内代码： ``行内代码``
* 分割符：
------
注：粗体斜体行内代码前后需要空格，可以用\ 转义避免产生空格。
分割符由大于4个 - 组成，前后需要添加换行。
- 斜体： 斜体
- 粗体： 粗体
- 行内代码：
行内代码 - 分割符：
3.2. 标题¶
标题使用符号 = - ` : ' " ~ ^ _ * + # < > 表示，按照出现顺序自动分级。
对于python文档，有一般约定：
# 带上划线，表示parts。
* 带上划线，表示chapters。
= 表示sections。
- 表示subsections。
^ 表示subsubsections。
" 表示paragraphs。
3.2.1. 标题示例¶
使用=-^表示三个层级标题。
3.2.2. 自动编号¶
.. toctree::
:numbered:
3.3. 段落¶
空一行是表示新起一个段落。段落之间间距较大，若是有关联的换行，考虑\ **列表**\ 。
可以使用缩进，表示缩进的段落。
可以连续使用缩进
空一行是表示新起一个段落。段落之间间距较大，若是有关联的换行，考虑列表。
可以使用缩进，表示缩进的段落。
可以连续使用缩进
3.4. 列表¶
3.4.1. 有序列表¶
1. 枚举的类型有:
a. 阿拉伯数组: 1, 2, 3 ...
b. 大小写字母: A-Z 或 a-z
c. 大小写罗马字母: I, II, III, IV, ... 或 i, ii, iii, iv ...
2. 使用 **#** 自动生成枚举序号，可以从任一数字开始
4. xxx
#. yyy
#. zzz
枚举的类型有:
- 阿拉伯数组: 1, 2, 3 …
- 大小写字母: A-Z 或 a-z
- 大小写罗马字母: I, II, III, IV, … 或 i, ii, iii, iv …
使用 # 自动生成枚举序号，可以从任一数字开始
- xxx
- yyy
- zzz
3.4.2. 无序列表¶
* 可以使用 ``* + -`` 表示
* xxx
* 没有空一行的话，xxx会加粗; 反之不会
* 缩进表示二级列表
* 继续一级列表，不需要空行
可以使用
* + -表示xxx
- 没有空一行的话，xxx会加粗; 反之不会
- 缩进表示二级列表
继续一级列表，不需要空行
3.5. 块¶
3.5.2. 代码块¶
pygments.lexers.get_all_lexers()可列出支持的代码类型。
.. code-block:: python
:linenos:
def my_function():
print('just a test', 8 // 2)
print 8/2
linenos可以打开行号。
1 2 3 | def my_function(): print('just a test', 8 // 2) print 8/2 |
3.5.3. 文档测试块¶
文档测试块是交互式的Python会话，以 >>> 开始，一个空行结束。
>>> print('This is a doctest block.')
This is a doctest block.
3.5.4. 注解提示块¶
.. note::
这是注解. note会执行(替换下面的#号)，但是单纯的文本块::不会。
4. xxx
#. yyy
#. zzz
块都支持缩进显示:
.. Tip:: 这里是缩进的提示内容。
Note
这是注解. note会执行(替换下面的#号)，但是单纯的文本块::不会。
- xxx
- yyy
- zzz
块都支持缩进显示:
Tip
这里是缩进的提示内容。
3.5.5. 行块¶
下面是行块内容：
| 和缩进的区别
| 间距是行距
而缩进:
缩进的间距是段落间距。
上面这个间距很大。
行块使用|, 前后各有一个空格。
- 下面是行块内容：
- 和缩进的区别间距是行距
而缩进:
缩进的间距是段落间距。
上面这个间距很大。
3.5.6. 数学公式块¶
.. math::
\ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
l_n = \left( x_n - y_n \right)^2.
\[\ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad
l_n = \left( x_n - y_n \right)^2.\]
多行公式
\[\begin{split}\begin{align}
a_{11}& = b_{11}& a_{12}& = b_{12}+c_{12}\\
a_{21}& = b_{21}& a_{22}& = b_{22}+c_{22}
\end{align}\end{split}\]
3.6. 链接¶
3.6.1. 外部链接¶
详细内容请参考 `reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_。
详细内容请参考 reStructuredText Primer。
3.7. 图片¶
.. image:: https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png
:height: 300 px
:width: 600 px
:scale: 50 %
:alt: 图片无法打开时显示
:align: center
3.8. 表格¶
3.8.1. 简单表格¶
来自 Open-ReID 的例子。
========= ============ ======== ============ ========== ==============
Net Loss Mean AP CMC allshots CMC cuhk03 CMC market1501
========= ============ ======== ============ ========== ==============
Inception Triplet N/A N/A N/A N/A
Inception Softmax 65.8 48.6 73.2 71.0
Inception OIM 71.4 56.0 77.7 76.5
ResNet-50 Triplet **80.7** **67.9** **84.3** **85.0**
ResNet-50 Softmax 62.7 44.6 70.8 69.0
ResNet-50 OIM 72.5 58.2 77.5 79.2
========= ============ ======== ============ ========== ==============
| Net | Loss | Mean AP | CMC allshots | CMC cuhk03 | CMC market1501 |
|---|---|---|---|---|---|
| Inception | Triplet | N/A | N/A | N/A | N/A |
| Inception | Softmax | 65.8 | 48.6 | 73.2 | 71.0 |
| Inception | OIM | 71.4 | 56.0 | 77.7 | 76.5 |
| ResNet-50 | Triplet | 80.7 | 67.9 | 84.3 | 85.0 |
| ResNet-50 | Softmax | 62.7 | 44.6 | 70.8 | 69.0 |
| ResNet-50 | OIM | 72.5 | 58.2 | 77.5 | 79.2 |
3.8.2. 网格表¶
可以使用 Tables Generator 来生成。但是center不是很容易。
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
+========================+============+==========+==========+
| 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. |
+------------------------+------------+---------------------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
|---|---|---|---|
| body row 1, column 1 | column 2 | column 3 | column 4 |
| body row 2 | Cells may span columns. | ||
| body row 3 | Cells may span rows. |
|
|
| body row 4 | |||