RST文档技巧汇总

前言

RST全称ReStructuredText，是一种使用简单标记语法编写文档的文本文件格式。RST文档是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助 Python 的 Docutils 项目进行文档处理，也可以转换为 HTML 或 PDF 等多种格式。

下文介绍转换工具和简洁语法，简洁语法包含注释、空行、标题、样式、链接、图片、列表、表格、代码块、文档内引用、引用rst、等等。

详细的语法可参考如下网站：
RST语法
RST简明教程

转换工具

Markdown to RST

网页工具：链接

此工具可将Markdown文档转换为RST文档，属于一个过渡工具，适合熟悉Markdown但刚接触RST的新人使用；若熟悉RST语法，推荐直接使用RST语法编写RST文档，这样更加可控且无需二次检查。

页面展示：

简洁语法

注释

单行注释

.. 注释内容

多行注释

..
 注释内容
 注释内容

空行

在rst源代码中使用 | 可以表示空行。

标题与章节

==== 至少和文字行一样长，或者更长。
相同级别必须使用统一的符号, 否则会被识别为更小的级别。
= - ~ ` : ’ " ^ _ * _ # < > 这些符号都可以区分级别。
标题和章节在结构上的作用相同，但是可能有不同的显示格式。

标题

============
一级标题
============

------------
二级标题
------------

章节

一级章节
============

二级章节
------------

三级章节
~~~~~~~~~~~~

四级章节
############

样式

*斜体*
**粗体**
`引用`
``行内代码块``

上标：
$E=m{c}^2$

E = mc\ :sup:`2`

下标：
$H_{2}O$

H\ :sub:`2`\ O

转义：
*BSD

\*BSD

链接

访问 `我的博客 <https://blog.csdn.net/NSJim>`_ 可以了解更多信息。

图片

简单图片

.. figure:: ../assets/pic.png
# or
.. image:: ../assets/pic.png

复杂图片

.. figure:: ../assets/yolov5s.png
   :height: 13cm
   :align: center

   YOLOv5s编译效果对比

列表

列表前后以及条目之间必须有空行隔开，下级列表需要有空格缩进。列表下面可以插入任意的内容，段落或图片都可以，但要求段落左侧空格缩进和列表的第一个文字对齐。

无序列表

+ 一级列表1

  - 二级列表

    * 三级列表

+ 一级列表2

  段落

+ 一级列表3

其中，无序列表可以使用 + 、 - 、 * 来表示。显示效果如下：

有序列表

1. 一级列表1

#. 一级列表2

   a. 二级列表

      段落

#. 一级列表3

其中，第二条开始后续的条目用 # 开头。显示效果如下：

表格

.. list-table:: 表格标题
   :widths: 20 10 50
   :header-rows: 1

   * - 参数名
     - 必选
     - 说明
   * - name
     - 是
     - 名称
   * - input
     - 是
     - 输入
   * - output
     - 否
     - 输出

其中，widths表示每一列的宽度比例。显示效果如下：

代码块

行内代码块

``行内代码块``

多行代码块

.. code-block:: shell
   :linenos:

   def sort_bubble_my(arr):
       arr_len = len(arr)
       for i in range(arr_len):
           for j in range(i+1, arr_len):
               if arr[i] > arr[j]:
                   arr[i], arr[j] = arr[j], arr[i]
       return arr

其中，linenos 表示显示行号。

文档内引用

# 引用位置
.. _env setup:

# 引用
:ref:`开发环境配置章节 <env setup>`

# 示例
参考 :ref:`开发环境配置章节 <env setup>` 完成环境配置。

引用rst

.. include:: get_resource.rst