3. reST语法介绍¶

reStructuredText标记语言比Markdown强大很多，支持多种排版样式。不过这里只介绍开发人员主要会用到的一些样式。reST文档的详细介绍见http://docutils.sourceforge.net/rst.html

3.1. 章节标题¶

在文本下一行（或上一行）添加至少与文本长度同宽的符号，即可以使文本成为标题。但并没有规定某一个级别的标题必须用什么字符，可以参考python文档的一些约定:

* # with overline, for parts
* * with overline, for chapters
* =, for sections
* -, for subsections
* ^, for subsubsections
* ", for paragraphs

我们把intro.rst改成下面这样:

intro
=====

aaa

aaaaaaaaaaaa

bbbb

bbbbbbbbbbb

其中，intro是一级标题，aaa和bbbb是二级标题。生成的html标签分别是<h1>和<h2>。回到上一级目录重新make html，此时首页index.html效果如下：

在右边的Contents中，sphinx已经给我们生成了各文件的标题链接，深度为2，深度可以在index.rst中的maxdepth中设置。然而index.html左边的导航里并没有各文件的链接，像intro.html里那样，这个可以通过修改conf.py实现，找到html_sidebars，改为:

html_sidebars = { '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html']}

修改后保存，重新make html，index.html左边导航变为如下这样：

注解

有些主题(theme)会自动完成添加左侧导航的功能

3.2. 段落¶

段落是构成reST文档的基本单位。通过一个或一个以上的空行隔开的文本区块就是一个段落。正如在python里一样，reST中的缩进非常重要。同一段落的多个文本行必须有一样的缩进。

注意在段落内换行并不会在html中生成换行符，要想保持在文本编辑器中的换行符，需要在这些行前面加上|和空格:

| aaaaaaaa
| bbbbbbbbb
| cccccccccccc

效果:

aaaaaaaa
bbbbbbbbb
cccccccccccc

注解

如果编写中文reST文档，在编辑器中由于一行文字太长需要强制换行时，记得在行末加\，否则生成的html会在行末和下一行行首之前插入一个空格

3.3. 行内标记¶

行内标记常用的有:

字体加粗两个星号
字体倾斜一个星号
代码或内容引用两个反引号（`）

示例:

aaaa **加粗** aaaaa
aaaa *倾斜* aaaaa
aaaaa ``引用`` aaaaaa

效果：

aaaa 加粗 aaaaa aaaa 倾斜 aaaaa aaaaa 引用 aaaaaa

注意这些符号在前后不能有非空白字符，否则无法生效。

3.4. 列表¶

符号列表 *号后空格
编号列表数字加点加空格，或者#号加点加空格
定义列表术语（只能一行）的下一行缩进，下一行为定义内容

示例:

* item
* item
* item

1. item1
2. item2
3. item3

#. item4
#. item5
#. item6

FOO
    this is very interesting.

BAR
    this is interesting, too.

效果：

item
item
item

item1
item2
item3
item4
item5
item6

FOO: this is very interesting.
BAR: this is interesting, too.

3.5. 代码¶

在文档中列出代码是开发人员经常用到的一个功能。在reST文档中列出代码有三种方式：

行内代码用``code``
简单代码块在代码块的上一个段落后面加2个冒号，空一行后开始代码块，代码块要缩进
复杂代码块使用code-block指导语句，还可以选择列出行号和高亮重点行等

示例:

source code below ::

void foo()
{
    int i;

    for(i=0; i<10; i++)
    printf("i: %d\n", a);
}

source code again

.. code-block:: c
    :linenos:
    :emphasize-lines: 3,6

    void foo()
    {
        int i;

        for(i=0; i<10; i++)
        printf("i: %d\n", a);
    }

效果：

source code below

void foo()
{
    int i;

    for(i=0; i<10; i++)
    printf("i: %d\n", a);
}

source code again

void foo()
{
    int i;

    for(i=0; i<10; i++)
    printf("i: %d\n", a);
}

3.6. 超链接¶

主要有两种方式：

行内超链接语法`链接文字 <URL>`_
分开的超链接用到链接的地方`链接文字`_, 定义链接的地方 .. _链接文字: URL
记住链接URL要加http://前缀，不要直接从网址开始写。

示例:

visit `baidu <http://www.baidu.com>`_

visit `baidu URL`_

.. _baidu URL: http://www.baidu.com

效果：

visit baidu

visit baidu URL

3.7. 图片¶

使用image指导语句。

示例:

baidu logo:

.. image:: img/bdlogo.png
    :width: 200px

效果：

baidu logo:

也可以使用figure指导语句，figure可以空一行，接着写图片标题。

示例:

.. figure:: img/bdlogo.png
    :width: 200px

    Baidu LOGO

效果：

Baidu LOGO

3.8. 表格¶

使用文本字符绘制的表格。简单表格用的字符较少，但功能有限，如不能表格行不能换行；复杂不及格使用的字符较多。

示例:

simple table:

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

grid table:

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

效果:

simple table:

Inputs		Output
A	B	A or B
False	False	False
True	False	True
False	True	True
True	True	True

grid table:

Header row, column 1 (header rows optional)	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.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.

3.9. 引用¶

一种是传统的参考文献引用格式。

示例:

It is methioned by [Ref]_ that C++ is good.

.. [Ref] 《zzq's talk》

效果：

类似于书签的引用，被引用的内容可以在另一个reST文档中。在引用的地方, 使用 :ref:`bookmark` 这种语法，在被引用内容的上方, 使用 _bookmark: 的语法。下方的标题将变成书签链接的文本。

示例:

附录 :ref:`ewma_algo` 中也有介绍。

.. _ewma_algo:

EWMA Algo
---------
(被引用的内容）

文档间引用，引用另一文档，格式是 :doc:`file_name` 。

示例:

sniper知识库格式发生了一些变化，见 :doc:`rule_format` 。

3.10. 脚注¶

与引用语法类似，只是它在正文中显示的不是文本，而是编号。

示例:

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

Footnotes

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

效果：

3.11. 提醒¶

可以使用提醒指导语句来添加需要提醒读者注意的说明文字。

示例:

.. note:: this is a note.

.. warning:: this is a warning.

.. error:: this is an error.

效果:

注解

this is a note.

警告

this is a warning.

错误

this is an error.

已实现的提醒指导语句有：

attention
caution
danger
error
hint
important
note
tip
warning

3.12. 替换¶

替换类似脚注，在正文中使用|text|这样标签，然后可以设定使用其他文本或者图片来代替text这个占位符。

示例:

I like eat |apple| very much.

.. |apple| replace:: 苹果

效果:

I like eat 苹果 very much.