Python 开发者的文档利器：掌握 .rst 文件与 Sphinx 的使用技巧.rst 文件是 reStructure

.rst 文件是 reStructuredText 的文件扩展名。

reStructuredText（通常简称为 RST、ReST 或 reST）是一种轻量级标记语言，主要在 Python 编程语言社区中广泛用于技术文档的编写。

reStructuredText 的主要特点和用途：

纯文本格式: .rst 文件是纯文本文件，这意味着你可以使用任何文本编辑器打开和编辑它们。它们的语法设计目标是让即使不经过解析，原始的纯文本内容也具有良好的可读性，类似于 Markdown。
技术文档: RST 最主要的用途是编写技术文档，特别是 Python 项目的官方文档。例如，Python 官方文档、许多 Python 库（如 NumPy, SciPy, Django 等）的文档都是用 RST 编写的。
Docutils: reStructuredText 是 Docutils 项目的一部分。Docutils 是一个 Python 库，用于将纯文本文件（包括 RST 格式）解析并转换为各种输出格式，如 HTML、LaTeX、XML 等。
Sphinx: 自 2008 年以来，RST 一直是 Sphinx 文档生成系统的核心组件。Sphinx 是一个强大的文档工具，广泛用于生成高质量的、可索引的、包含交叉引用的技术文档网站和 PDF 手册。如果你看到一个用 Sphinx 构建的文档网站，那么它的源文件很可能就是 .rst 文件。
易于学习和编写: 相比于更复杂的标记语言（如 HTML 或 LaTeX），RST 的语法更简洁、直观，易于学习和编写。它使用简单的符号和约定来表示标题、列表、代码块、链接、表格等结构。
可扩展性强: RST 提供了强大的 "role" (角色) 和 "directive" (指令) 机制，允许用户和工具开发者创建自定义的标记和功能，从而极大地增强了表达能力和灵活性。这使得它在处理复杂的技术文档时比 Markdown 更有优势。
统一的解析: 无论在哪个平台，RST 的解析功能都统一在 Docutils 模块下，这有助于保证文档的一致性和可移植性，避免了像某些 Markdown 实现那样因扩展标准不统一而导致的兼容性问题。

简单语法示例：

代码段

.. _introduction:

==============
这是主标题
==============

------------------
这是副标题
------------------

这是一个普通段落。

这是一个 **粗体** 文本，这是一个 *斜体* 文本。

* 这是一个无序列表项
* 另一个列表项

1. 这是一个有序列表项
2. 另一个有序列表项

.. code-block:: python

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

这是一个 `外部链接 <https://www.python.org>`_。

.. note::
   这是一个提示框。

如何转换 rst 文件

创建和编辑 .rst 文件后，要将其转换为网页（HTML 格式）并显示，你需要使用 Docutils 或更常用且功能更强大的 Sphinx。

使用 Docutils (最简单，适合单个文件)

Docutils 是 reStructuredText 的解析器和转换器。它包含一个名为 rst2html.py 的脚本，可以将 .rst 文件直接转换为 HTML。

步骤：

安装 Docutils:
```
pip install docutils
```
转换 .rst 文件到 HTML: 打开你的命令行或终端，导航到 .rst 文件所在的目录，然后运行 rst2html.py 命令：
```
rst2html.exe your_document.rst your_document.html
```
- your_document.rst 是你的 reStructuredText 文件。
- your_document.html 是你希望生成的 HTML 文件名。
在浏览器中打开 HTML 文件: 转换成功后，你的目录中会生成一个 your_document.html 文件。你可以直接在文件浏览器中双击这个 HTML 文件，或者在命令行中使用以下命令（根据你的操作系统）：
- Windows:
```
start your_document.html
```
- macOS:
```
open your_document.html
```
- Linux:
```
xdg-open your_document.html
```
这将在你的默认网页浏览器中打开生成的 HTML 页面，显示你的 .rst 文档内容。

优点: 简单快捷，适合单个 .rst 文件或非常简单的文档。

缺点: 不支持多文件项目、复杂的交叉引用、搜索功能或自定义主题。对于大型项目，建议使用 Sphinx。

使用 Sphinx (推荐用于复杂项目和多文件文档)

Sphinx 是一个更高级的文档生成系统，它建立在 Docutils 之上，并提供了丰富的功能，如多文件支持、交叉引用、搜索功能、多种主题、扩展插件等。它是 Python 项目文档的事实标准。

步骤：

安装 Sphinx:
```
pip install sphinx
```
初始化 Sphinx 项目:

导航到你希望存放文档的根目录（通常是你的项目根目录下的 docs/ 文件夹），然后运行 sphinx-quickstart 命令。
```
mkdir docs
cd docs
sphinx-quickstart.exe
```
sphinx-quickstart 会引导你完成一些配置问题，例如项目名称、作者、版本等。其中最重要的是：
- 独立的源文件和构建目录 (y/n): 建议输入 y。这会在 docs 目录下创建 source/ 和 build/ 两个子目录，源文件放在 source/，生成的 HTML 文件放在 build/。
- 项目名称
- 作者名称
- 项目发行版本
- 语言：如果是中文，输入 zh_CN，其它语言查询 Configuration — Sphinx documentation
完成 sphinx-quickstart 后，你的 docs/ 目录下会生成一些文件和目录，其中最重要的文件是 source/conf.py (Sphinx 配置文件) 和 source/index.rst (主文档入口)。
将你的 .rst 文件放入 source/ 目录:

将你创建和编辑的 .rst 文件（例如 my_article.rst）复制或移动到 docs/source/ 目录下。
在 index.rst 中引用你的文件 (如果需要):

如果你有多个 .rst 文件，或者希望将你的文件作为整体文档的一部分，你需要在 source/index.rst 中引用它。在 index.rst 中找到 .. toctree:: 指令，并添加你的文件名（不带 .rst 后缀）：

这里我在 docs/ 下创建了 quick_start 文件夹，然后在 quick_start 文件夹下创建了 quick_Start.rst 文件。

注意文件夹最好不要有空格， quick start 是不推荐的，最好使用下划线，文件同理。

然后在 index.rst 中添加

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   quick_start/quick_start

构建 HTML 文档:

在 docs/ 目录下（make.bat 所在的目录），运行以下命令来构建 HTML：
```
make.bat html
```
这个命令会根据 source/ 目录下的 .rst 文件和 conf.py 配置，在 docs/build/html/ 目录下生成所有 HTML 文件。
在浏览器中打开生成的 HTML 文件:

构建成功后，导航到 docs/build/html/ 目录。你会看到一个 index.html 文件（这是你的文档主页）以及其他相关的 HTML 文件和资源。

你可以直接双击 index.html 文件，或者像 Docutils 方法一样使用命令行打开它：
- Windows: start docs\build\html\index.html
- macOS: open docs/build/html/index.html
- Linux: xdg-open docs/build/html/index.html