reStructuredText 全面教程：从基础语法到实践应用

reStructuredText 全面教程：从基础语法到实践应用

reStructuredText（简称reST或RST）是一种轻量级标记语言，主要用于Python技术文档的编写，也是Sphinx文档生成器的默认输入格式。本教程将系统介绍reST的语法规则、核心功能以及实际应用场景。

1. reStructuredText简介

reStructuredText是Python Docutils项目的一部分，设计目的是：

• 为Python创建类似Javadoc的文档工具
• 保持源文件高度可读性，使用自然简单的语法规则
• 支持复杂文档结构的精细控制，比Markdown功能更强大

主要特点：

• 类似Python的语法：通过缩进宽度定义元素，段落使用空行分隔
• 优化的符号体系：如**强调**代替HTML的粗体或LaTeX的\textbf{粗体}
• 结构化强制：标题必须加下划线等规则保证文档结构清晰

2. 基础语法

2.1 段落与缩进

段落是reST最基本的结构，由空行分隔的文本块组成：

• 同一段落的所有行必须左对齐且缩进级别相同
• 缩进的段落被视为引文

示例：

这是一个普通段落。
同一段落的第二行。

    这是缩进段落，通常表示引言。
    
恢复普通段落。

2.2 标题与章节

标题通过下划线符号创建，MegEngine规范推荐：

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

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

三级标题
~~~~~~~~

注意事项：

• 标记符必须与文本长度一致
• 可以使用#=-~:'"^_*+<>等符号，但同一级别应保持一致
• 标题也可用双划线包围：

====
标题
===&#