############################
如何编写标题?
############################
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(段落) | ``"`` |
+---------+------------------------+--------------+