RST语法

1. 认识 reStructuredText：文档界的“工业模具”

在大多数人习惯了 Markdown (MD) 的轻便快捷时，reStructuredText (RST) 则代表了另一种哲学：严谨、标准与高度可扩展。

1.1. 什么是 RST？

RST 是一种轻量级的标记语言，它是 Python 社区的官方文档标准。如果说 Markdown 像是一张随手记录的 便签纸，那么 RST 更像是一套 工业模具。

1.2. 核心设计哲学：语义化

RST 的强大源于其“指令 (Directives)”系统。在 MD 中，如果你想做一个警告框，你可能需要用 HTML 标签或者特殊的引用符号；但在 RST 中，这被定义为一种 语义化区块：

Markdown：> **注意**：请备份数据（仅靠视觉加粗）
RST：.. warning:: 请备份数据（明确告诉解析器，这是一个“警告”类型的逻辑块）

2. 为什么需要 Sphinx？（工具链的价值）

RST 只是原材料，而 Sphinx 则是加工厂。

2.1. 文档工程化（Documentation As Code）

Sphinx 将编写文档的过程“程序化”了。它的核心优势在于：

全局索引：自动生成详尽的目录树（TOC）、索引页和术语表。
交叉引用：可以跨文件引用某个函数或章节，当目标位置改变时，引用会自动更新，不会出现死链接。
代码集成：通过 autodoc 扩展，Sphinx 可以直接读取 Python 源代码中的注释（Docstrings），实现“代码即文档”。

3. 选型指南：我该从 Markdown 切换到 RST 吗？

这是一个权衡（Trade-off）的过程。我们可以用“装修”来做比喻：

Markdown (精装公寓)：拎包入住。对于大多数中小型项目、博客、README 来说，MD 的简单和直观是无敌的。
RST + Sphinx (自建别墅)：你需要设计图纸（配置文件），学习如何打地基（语法规范），但最终你能得到一个完全按需定制、结构极其稳固的系统。

3.1. 决策矩阵

维度	保持使用 Markdown	引入 RST + Sphinx
文档体量	单页或数个独立页面	庞大的技术手册、多章节书籍
逻辑复杂性	线性阅读	频繁的跳转引用、复杂的参数列表
自动化需求	手写为主	自动提取代码注释生成 API 文档
团队背景	通用开发、非技术人员	Python 开发者、专业文档工程师

4. 实战演示：从零构建一个专业文档项目

为了快速回顾，我们以构建一个名为 SuperMath 的工具文档为例。

4.1. Step 1: 环境配置

pip install sphinx sphinx-rtd-theme

4.2. Step 2: 初始化工程

运行 sphinx-quickstart。

关键建议：启用 Separate source and build directories。这会让你的源码（rst）与生成的产物（html）互不干扰，保持项目整洁。

4.3. Step 3: 核心语法实操

创建一个 feature.rst 文件，尝试以下 RST 独有的高级特性：

功能特性
========

.. sidebar:: 快速导航
   :subtitle: 本页重点内容

   * 公式推导
   * 性能对比

数学能力
--------
我们支持通过 LaTeX 渲染复杂的数学公式：

.. math::
   f(x) = \int_{-\infty}^{\infty} e^{-x^2} dx

复杂数据展示
------------
RST 处理复杂表头和合并单元格的能力远超 Markdown：

+------------------------+------------+----------+
| 模块名称               | 性能评分   | 稳定性   |
+========================+============+==========+
| 核心计算引擎 (Core)    | 9.8        | 极高     |
+------------------------+------------+----------+
| 插件适配器 (Plugin)    | 7.5        | 中等     |
+------------------------+------------+----------+

.. tip::
   建议在生产环境下优先使用核心计算引擎。

4.4. Step 4: 编译与预览

在根目录执行 make html (Linux/Mac) 或 .\make.bat html (Windows)。

Sphinx 会扫描所有 rst 文件，处理它们之间的交叉引用关系，并生成一个支持全文搜索的静态网站。

5. 总结：优劣势回顾

5.1. 优势 (Pros)

强大的表达力：原生支持公式、警告框、侧边栏等专业排版元素。
逻辑严密：适合作为大型软件的官方技术规范。
生态配套：配合 Read the Docs 平台，可以实现代码提交后文档自动发布。

5.2. 劣势 (Cons)

语法严格：多一个空格或少一个缩进都可能导致解析失败。
预览延迟：不像 MD 随写随看，RST 通常需要编译后查看最终效果。

6. 参考资料

RST
Sphinx