如何编写标题？

reStructuredText（RST）没有固定规定某个符号一定对应几级标题，而是通过不同的标点符号来区分层级，RST 只关心：

• 同一种修饰符号代表同一个层级。

• 不同符号代表不同层级。

• 各层级之间保持一致的父子关系。

• 标题上下的符号数量必须不少于标题字符数（通常保持相同长度）

但是，对于 Python 文档，这里有一个建议的约定：

层级	名称（Python文档）	符号
Level 1	Part（部分）	#
Level 2	Chapter（章节）	*
Level 3	Section（节）	=
Level 4	Subsection（小节）	-
Level 5	Subsubsection（子小节）	^
Level 6	Paragraph（段落）	"

# 与 * 可接受上划线（可选）和下划线，其他符号只接受下划线。

源码如下：

####################
第一部分：基础知识
####################

****************
第一章：环境搭建
****************

安装 GCC
========

Windows 环境
------------

安装 MinGW
^^^^^^^^^^

下载步骤
""""""""

这是 Python 文档项目自己的风格约定，不是 reStructuredText 的语法要求。

实际上 Sphinx 官方文档、ReadTheDocs、大多数开源项目通常只用：

• = 代表一级标题

• - 代表二级标题

• ^ 代表三级标题

• " 代表四级标题

其他符号很少使用。

这是一级标题

源码如下：

这是一级标题
=======================================

这是二级标题

源码如下：

这是二级标题
----------------------------------------

这是三级标题

源码如下：

这是三级标题
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

这是四级标题

源码如下：

这是四级标题
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

如何编写列表？

列表分为有序列表与无序列表. 无序列表长这样：

• 黄金时代

• 白银时代

• 黄铜时代

语法如下：

* 黄金时代
* 白银时代
* 黄铜时代

有序列表长这样：

1. 黄金时代

2. 白银时代

3. 黄铜时代

1. 黄金时代
2. 白银时代
3. 黄铜时代

如何编写特殊提示？

效果如下

Note

This is a note admonition. This is the second line of the first paragraph.

• The note contains all indented body elements following.

• It includes this bullet list.

源码如下：

.. note:: This is a note admonition.
 This is the second line of the first paragraph.

 - The note contains all indented body elements
   following.
 - It includes this bullet list.

如何插入图片？

源码如下：

.. image:: ../_static/postman.png

如何插入音频？

崔健-蓝色骨头

上面是一个音频的嵌入，源码如下：

.. raw:: html

        <audio controls="controls">
                <source src="../_static/cuiain_blue.mp3" type="audio/mpeg">
        </audio>

如何插入动态图表？

上面是一个hignchart表格的嵌入，源码如下：

.. raw:: html

            <embed>
                    <div id="zhexian" style="min-width:400px;height:400px"></div>
                    <script>
                            var chart = Highcharts.chart('zhexian', { title: { text: '2010 ~ 2016 年太阳能行业就业人员发展情况' }, subtitle: { text: '数据来源：thesolarfoundation.com' }, yAxis: { title: { text: '就业人数' } }, legend: { layout: 'vertical', align: 'right', verticalAlign: 'middle' }, plotOptions: { series: { label: { connectorAllowed: false }, pointStart: 2010 } }, series: [{ name: '安装，实施人员', data: [43934, 52503, 57177, 69658, 97031, 119931, 137133, 154175] }, { name: '工人', data: [24916, 24064, 29742, 29851, 32490, 30282, 38121, 40434] }, { name: '销售', data: [11744, 17722, 16005, 19771, 20185, 24377, 32147, 39387] }, { name: '项目开发', data: [null, null, 7988, 12169, 15112, 22452, 34400, 34227] }, { name: '其他', data: [12908, 5948, 8105, 11248, 8989, 11816, 18274, 18111] }], responsive: { rules: [{ condition: { maxWidth: 500 }, chartOptions: { legend: { layout: 'horizontal', align: 'center', verticalAlign: 'bottom' } } }] } });
                    </script>
            </embed>

如何编写代码块？

import yaml

print('hello')

源码如下：

.. code-block:: python

    import yaml

    print('hello')

如何插入CSV表格？

表格描述

作者	备注
lee	我真的服了
yorke	啊哈哈哈哈哈

源码如下：

.. csv-table:: 表格描述
    :header: 作者,备注
    :widths: 3,10

    lee,我真的服了
    yorke,啊哈哈哈哈哈

如何插入Grid Table表格？

Note

表格需要严格对齐

层级	名称（Python文档）	符号
Level 1	Part（部分）	#
Level 2	Chapter（章节）	*
Level 3	Section（节）	=
Level 4	Subsection（小节）	-
Level 5	Subsubsection（子小节）	^
Level 6	Paragraph（段落）	"

源码如下：

+---------+------------------------+--------------+
| 层级    | 名称（Python文档）     | 符号         |
+=========+========================+==============+
| Level 1 | Part（部分）           | ``#``        |
+---------+------------------------+--------------+
| Level 2 | Chapter（章节）        | ``*``        |
+---------+------------------------+--------------+
| Level 3 | Section（节）          | ``=``        |
+---------+------------------------+--------------+
| Level 4 | Subsection（小节）     | ``-``        |
+---------+------------------------+--------------+
| Level 5 | Subsubsection（子小节）| ``^``        |
+---------+------------------------+--------------+
| Level 6 | Paragraph（段落）      | ``"``        |
+---------+------------------------+--------------+