Title & Paragraph¶

标题和段落是 reST 文档的基础，绝大多数的文档也都是由这两者构成。在本篇中，我们会学习到如何使用不同层级的标题，如何编写不同结构的段落。掌握了这些内容，就能够处理绝大多数的文档编写工作。

标题¶

在 reST 中，标题代表了一个段落（小节）的开始，在不同的标题之间也存在着不同的层级。合理的运用标题可以让你的文章逻辑更清晰，结构更明了。

标题的层级¶

在 rst 文档中，标题的层级由高到低通常分为以下几个层级：

在标题上下方加上长度相等的 # 构成的篇章标题
在标题下方加上 = 的小节标题
在标题下方加上 - 的段落标题
在标题下方加上 ^ 的小标题

对于标题来说，reST 的语法要求分隔符的长度必须要超过标题的文本长度，除此之外，标题文本的上下方还不能有多余的空行和多余的缩进

示例代码¶

========================
Level 1
========================

Level 2
=================

Level 3
-----------------

Level 4
^^^^^^^^^^^^^^^^^

段落¶

普通的换行在 reST 中并不能实现真正的分段，要在 reST 中实现分段需要连续的两个换行。除此之外， reST 对空格也会很敏感，在之后的一些的例子中，缺少空格或者有额外空格都会导致格式解析的错误，在这里先做一个说明。

列表¶

类似于 Markdown 那样， reST 的列表也是由 * 、 1. 、 #. 这些符号开头构成的。

* list1
* list2
    * list 3
    * list 4
* list 5

1. aaa
2. bbb
3. ccccc


#. number 1
#. number 2
    #. number 3

效果

list

list1
list2
- list 3
- list 4
list 5

aaa
bbb
ccccc
number 1
number 2
1. number 3

引用段落¶

在 reST 中，要创建引用段落只需要在段落前面加上一个缩进即可。

这是一个引用段落

引用段落可以有多行

效果

list

这是一个引用段落

引用段落可以有多行

代码段落¶

在`THUNLP Docs`中，代码使用 Pygments 进行高亮，在需要展示的代码前面加上 .. code-block:: language 指令即可。其中 language 需要根据你使用的语言进行替换

Pygments 目前支持多种语言，语言的列表可以参考 Supported Languages - Pygments 。

在使用代码段落时，还可以添加 linenos 属性，来让代码显示行号。

.. code-block:: python
    :linenos:

    >>> import tqdm
    Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
    ImportError: No module named tqdm

效果

list

>>> import tqdm
Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
ImportError: No module named tqdm

Doctest 段落¶

Doctest 段落是一种简化的 code-block ，它主要用于显示 Python 控制台的交互信息。不需要使用额外的指令，只需要在段落的前后加上空行即可。

>>> import torch
>>> a = torch.randn(3, 4, 5)
>>> a
tensor([[[-0.3844,  0.6536,  0.1193,  0.1505, -0.2724],
        [-0.3935,  0.3856, -0.6827,  1.2655, -0.4175],
        [ 0.4130, -0.2260,  0.8132, -1.5421, -1.2834],
        [-0.7414, -0.4651, -1.2076,  1.5439,  0.0098]],
        [[-0.0680,  0.3104, -0.1375, -0.9828,  2.6813],
        [-1.6662,  0.4071,  0.2930,  0.5446, -0.4448],
        [ 0.3892, -0.5734,  0.9870,  2.7067,  1.8806],
        [ 0.1683, -0.4734, -0.8124,  0.0481, -0.0406]],
        [[-1.9304, -1.7649, -0.4132,  0.6277, -0.1785],
        [-0.0390,  0.5194,  0.6192,  0.6247, -0.3684],
        [-0.6575,  0.2443, -0.1555,  0.9710, -0.6031],
        [ 0.5419, -0.2958,  0.6971, -0.1619, -1.4072]]])

效果

list

>>> import torch
>>> a = torch.randn(3, 4, 5)
>>> a
tensor([[[-0.3844,  0.6536,  0.1193,  0.1505, -0.2724],
        [-0.3935,  0.3856, -0.6827,  1.2655, -0.4175],
        [ 0.4130, -0.2260,  0.8132, -1.5421, -1.2834],
        [-0.7414, -0.4651, -1.2076,  1.5439,  0.0098]],
        [[-0.0680,  0.3104, -0.1375, -0.9828,  2.6813],
        [-1.6662,  0.4071,  0.2930,  0.5446, -0.4448],
        [ 0.3892, -0.5734,  0.9870,  2.7067,  1.8806],
        [ 0.1683, -0.4734, -0.8124,  0.0481, -0.0406]],
        [[-1.9304, -1.7649, -0.4132,  0.6277, -0.1785],
        [-0.0390,  0.5194,  0.6192,  0.6247, -0.3684],
        [-0.6575,  0.2443, -0.1555,  0.9710, -0.6031],
        [ 0.5419, -0.2958,  0.6971, -0.1619, -1.4072]]])