reStructuredText (rst) 文档基础（自用）

reStructuredText（简称 rst）是一种轻量级标记语言，以其简洁性和强大功能被广泛应用于文档撰写，尤其在 Python 社区和 Sphinx 文档生成工具中经常用到。因为自己最近在撰写相关文档，所以这里也记录一下基本语法，方便自己查阅。

没有特别偏和难的语法，都是基础语法。

参考文档：

reStructuredText简明教程： https://python-web-guide.readthedocs.io/zh/latest/skillstack/rst.html

官网： https://docutils.sourceforge.io/rst.html

sphinx： https://www.sphinx-doc.org/

1 标题

标题使用不同长度的符号标记，常见符号有 =, -, ~

标题一
=====

副标题
-----

小标题
~~~~~

2 段落

只需换行即可分段。段落间可留空行，增强可读性

这是第一段文字，介绍项目背景和目标。

这是第二段，详细描述实现方案。

3 列表

• 无序列表 ：用 *, +, - 。

* 第一项
* 第二项
* 第三项

• 有序列表 ：用数字和点 . 引导，数字顺序不管，rst 会自动排序

1. 第一步
2. 第二步
3. 第三步

4 链接

使用 .. _label: 定义链接锚点，参考链接 <label_>_ 实现跳转

.. _example_link:

这是链接锚点

访问 `示例链接 <example_link_>`_

5 引用

通过行首缩进表示引用内容，rst 会自动识别并格式化

这是普通段落。

    这是引用部分，行首缩进显示。

6 代码块

使用 .. code-block:: 语言类型 指定代码语言，如 Python

.. code-block:: python

    def hello_world():
        print("Hello, World!")

7 表格

采用网格格式或简单格式创建表格，网格格式更灵活

+--------+--------+--------+
| 表头 1 | 表头 2 | 表头 3 |
+========+========+========+
| 单元格 | 单元格 | 单元格 |
+--------+--------+--------+
| 单元格 | 单元格 | 单元格 |
+--------+--------+--------+

8 注释

以 .. 开头的行是注释，不会在生成文档中显示。

.. 这是注释内容，用于记录编写思路或说明

9 指令

指令用于实现复杂功能，如插入图片、引用文献等，基本格式为 .. 指令名:: 参数。

.. image:: image.png
   :alt: 描述文字

10 指令进阶

10.1 指令参数

指令参数丰富多样，以图片指令为例，:scale: 控制缩放，:align: 设置对齐方式等。

.. image:: image.png
   :scale: 50%
   :align: right

10.2 自定义角色与指令

可通过 .. role:: 自定义角色名 定义新角色，用于特殊文本标记；指令也可自定义

.. role:: custom

这是使用自定义角色 :custom:`文本`

一个综合所有语法的 demo

=================
rst 文档示例
=================

-----------------
简介
-----------------

reStructuredText 是一款功能强大的标记语言，适用于技术文档编写。

    "rst 的简洁与灵活使其在文档领域备受青睐。" —— 文档爱好者

.. _features:

-----------------
特性
-----------------

rst 具备以下优势：

* **简洁易读** ：语法直观，易于上手。
* **功能丰富** ：支持表格、代码块、指令等元素。
* **兼容性强** ：与 Sphinx 等工具无缝集成。

代码示例：

.. code-block:: python

    print("Hello, rst!")

-----------------
使用指南
-----------------

安装 Sphinx：

::

    pip install sphinx

生成文档结构：

::

    sphinx-quickstart

插入图片：

.. image:: example.png
   :alt: 示例图片
   :scale: 30%
   :align: center

-----------------
参考链接
-----------------