markdown和reStructuredText语法简单比较

PyCharm默认的代码注释就是reStructuredText风格的, 加之之前学习《实验设计》这门课的时候, 用过readthedocs+sphinx写过文档, 其默认的格式就是reStructuredText风格的, 所以比较好奇 (当时我是使用markdown写的文档, 借助pandoc转换成的rst格式).

网上关于reStructuredText的教程很乱, 基本来源要么是官方文档, 但是说实在话这个文档的可读性并不好,以关于标题的介绍为例(如下图), 没有像markdown那样简单, 但是介绍得不清不楚, 你甚至不知道markdown里面的###用rst如何表示.所以最后我借助了Pandoc来进行对比, 并在在线rst编辑器上验证, 从而清楚快速地学习rst语法.

标题

markdown

# H1

## H2

### H3

#### H4

##### H5

###### H6

reStructuredText

H1
==

H2
--

H3
~~

H4
^^

H5
''

H6
  

注释: rst没有h6

列表

基本使用

markdown

- 项目
  * 项目
    + 项目

1. 项目1
2. 项目2
3. 项目3

- [ ] 计划任务
- [x] 完成任务

reStructuredText

-  项目

   -  项目
   
      -  项目

1. 项目1
2. 项目2
3. 项目3

-  ☐ 计划任务
-  ☒ 完成任务

Field List

PyCharm默认的docstring风格

表格

markdown

|           | 预测阳性T | 预测阴性P |
| --------- | --------- | --------- |
| 真实阳性T | TP        | FN        |
| 真实阴性P | FP        | TN        |

reStructuredText

========= ========= =========
\         预测阳性T 预测阴性P
========= ========= =========
真实阳性T TP        FN
真实阴性P FP        TN
========= ========= =========

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Yfiw5Edd-1577792595004)(markdown和reStructuredText语法比较/1575608053684.png)]

链接

链接 [baidu](https://www.baidu.com)

链接 `baidu`_

.. _baidu: https://www.baidu.com

图片

![](https://www.baidu.com/img/bd_logo1.png)

|logo|

.. |logo| image:: https://www.baidu.com/img/bd_logo1.png

代码块

​```python
import cv2 as cv
import numpy as np

def foo():
    pass
​```

.. code:: python

   import cv2 as cv
   import numpy as np

   def foo():
       pass

公式

单行公式

$x^2 + y^2 = z^2$

$x^2 + y^2 = z^2$

多行公式

$$
x^2 + y^2 = z^2
$$

$$ x^2 + y^2 = z^2 $$

总结

以上是最最基础的用法, 要详细一点的教程, 参见简易教程. 另外Typora编辑器支持将markdown导出为rst (内部也是基于Pandoc).