############################ 如何编写标题? ############################ reStructuredText(RST)没有固定规定某个符号一定对应几级标题,而是通过不同的标点符号来区分层级,RST 只关心: - 同一种修饰符号代表同一个层级。 - 不同符号代表不同层级。 - 各层级之间保持一致的父子关系。 - 标题上下的符号数量必须不少于标题字符数(通常保持相同长度) 但是,对于 Python 文档,这里有一个建议的约定: +---------+------------------------+--------------+ | 层级 | 名称(Python文档) | 符号 | +=========+========================+==============+ | Level 1 | Part(部分) | ``#`` | +---------+------------------------+--------------+ | Level 2 | Chapter(章节) | ``*`` | +---------+------------------------+--------------+ | Level 3 | Section(节) | ``=`` | +---------+------------------------+--------------+ | Level 4 | Subsection(小节) | ``-`` | +---------+------------------------+--------------+ | Level 5 | Subsubsection(子小节)| ``^`` | +---------+------------------------+--------------+ | Level 6 | Paragraph(段落) | ``"`` | +---------+------------------------+--------------+ ``#`` 与 ``*`` 可接受上划线(可选)和下划线,其他符号只接受下划线。 源码如下: .. code-block:: reStructuredText #################### 第一部分:基础知识 #################### **************** 第一章:环境搭建 **************** 安装 GCC ======== Windows 环境 ------------ 安装 MinGW ^^^^^^^^^^ 下载步骤 """""""" 这是 Python 文档项目自己的风格约定,不是 reStructuredText 的语法要求。 实际上 Sphinx 官方文档、ReadTheDocs、大多数开源项目通常只用: - ``=`` 代表一级标题 - ``-`` 代表二级标题 - ``^`` 代表三级标题 - ``"`` 代表四级标题 其他符号很少使用。 这是一级标题 ======================================= 源码如下: .. code-block:: reStructuredText 这是一级标题 ======================================= 这是二级标题 ---------------------------------------- 源码如下: .. code-block:: reStructuredText 这是二级标题 ---------------------------------------- 这是三级标题 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 源码如下: .. code-block:: reStructuredText 这是三级标题 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 这是四级标题 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 源码如下: .. code-block:: reStructuredText 这是四级标题 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ############################ 如何编写列表? ############################ 列表分为有序列表与无序列表. 无序列表长这样: * 黄金时代 * 白银时代 * 黄铜时代 语法如下: .. code-block:: reStructuredText * 黄金时代 * 白银时代 * 黄铜时代 有序列表长这样: 1. 黄金时代 2. 白银时代 3. 黄铜时代 .. code-block:: reStructuredText 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. 源码如下: .. code-block:: .. 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 :align: center :width: 50% 源码如下: .. code-block:: reStructuredText .. image:: ../_static/postman.png ############################ 如何插入音频? ############################ **崔健-蓝色骨头** .. raw:: html 上面是一个音频的嵌入,源码如下: .. code-block:: .. raw:: html ############################ 如何插入动态图表? ############################ .. raw:: html
上面是一个hignchart表格的嵌入,源码如下: .. code-block:: reStructuredText .. raw:: html
############################ 如何编写代码块? ############################ .. code-block:: python import yaml print('hello') 源码如下: .. code-block:: reStructuredText .. code-block:: python import yaml print('hello') ############################ 如何插入CSV表格? ############################ .. csv-table:: 表格描述 :header: 作者,备注 :widths: 3,10 lee,我真的服了 yorke,啊哈哈哈哈哈 源码如下: .. code-block:: reStructuredText .. 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(段落) | ``"`` | +---------+------------------------+--------------+ 源码如下: .. code-block:: reStructuredText +---------+------------------------+--------------+ | 层级 | 名称(Python文档) | 符号 | +=========+========================+==============+ | Level 1 | Part(部分) | ``#`` | +---------+------------------------+--------------+ | Level 2 | Chapter(章节) | ``*`` | +---------+------------------------+--------------+ | Level 3 | Section(节) | ``=`` | +---------+------------------------+--------------+ | Level 4 | Subsection(小节) | ``-`` | +---------+------------------------+--------------+ | Level 5 | Subsubsection(子小节)| ``^`` | +---------+------------------------+--------------+ | Level 6 | Paragraph(段落) | ``"`` | +---------+------------------------+--------------+