文档编辑：reStructuredText全面使用指南 — 第二部分 基础语法
文档编辑：reStructuredText全面使用指南 — 第二部分 基础语法
reStructuredText（简称RST或ReST）是一种轻量级的标记语言，用于编写结构化的文档。它由Python社区开发，并广泛应用于技术文档、书籍、博客文章等。reStructuredText的设计目标是简洁、易读且易于转换为其他格式（如HTML、ePub、PDF、LaTeX等）。
文中内容仅限技术学习与代码实践参考，市场存在不确定性，技术分析需谨慎验证，不构成任何投资建议。
目录
第一部分 介绍
- 什么是reStructuredText
- 为什么选择reStructuredText
- reStructuredText的应用场景
- 安装与环境配置
- 基本概念和术语
第二部分 基础语法
- 文档结构
- 标题与子标题
- 段落与换行
- 列表（无序列表、有序列表）
- 表格
- 引用块
- 脚注
- 字体样式
- 加粗、斜体、下划线等
- 链接
- 内部链接
- 外部链接
- 图片插入
- 特殊字符的处理
- 注释
- 简单示例文档创建
第三部分 进阶特性
-
自定义指令
.. code-block::使用说明.. image::进阶用法- 创建自定义角色
-
替换文本
-
角色
-
目录生成
-
包含其他文件
-
条件处理
-
扩展机制简介
-
高级表格格式化
-
数学表达式支持
-
文档国际化
第四部分 高级主题
-
使用Sphinx构建项目文档
- Sphinx简介
- 设置Sphinx项目
- 主题选择与定制
- 自动生成API文档
- 国际化支持
-
reStructuredText与其他工具集成
- 与GitBook结合
- 在Jupyter Notebook中使用
- 作为Markdown的替代方案
-
最佳实践
- 维护大型文档集
- 提高写作效率的小技巧
- 性能优化建议
第二部分 基础语法
6. 文档结构
6.1 标题与子标题
在reStructuredText中，标题通过在其下方（或上方和下方）使用特定的字符来定义。常用的字符包括等号=、短横线-、波浪线~、星号*、加号+和井号#。
- 标记部分：使用等号
=。 - 标记章节：使用短横线
-。 - 标记节：使用波浪线
~。 - 标记小节：使用星号
*。 - 标记子小节：使用加号
+。 - 标记段落：使用井号
#。
示例：
部分（Parts）
=============
章节（Chapters）
----------------
节（Sections）
~~~~~~~~~~~~~~
小节（Subsections）
*******************
子小节（Subsubsections）
++++++++++++++++++++++++
段落（Paragraphs）
##################
6.2 段落与换行
段落由连续的文本行组成。如果需要在段落中换行，可以使用两个空格后跟一个换行符。
示例：
这是一个段落。这是同一段落的另一行。
这是另一个段落。
6.3 列表
- 无序列表：使用星号
*、加号+或短横线-作为项目符号。 - 有序列表：使用数字后跟句点
6.、字母后跟句点a.或罗马数字后跟句点i.。
示例：
无序列表：
- 项目1
- 项目2
- 项目3
有序列表：
6. 项目1
7. 项目2
3. 项目3
6.4 表格
表格可以通过简单的文本格式创建。使用管道符|分隔列，使用短横线-定义表头。
示例：
+--------+--------+--------+
| 列1 | 列2 | 列3 |
+========+========+========+
| 数据1 | 数据2 | 数据3 |
+--------+--------+--------+
| 数据4 | 数据5 | 数据6 |
+--------+--------+--------+
6.5 引用块
引用块用于引用外部内容或代码示例。使用::开始一个引用块。
示例：
这是一个引用块：
::
这是引用的内容。
可以包含多行。
6.6 脚注
脚注用于在文档底部添加注释。使用[#]_标记脚注，并在文档末尾定义具体内容。
示例：
这是正文中的脚注引用。[#]_
.. [#] 这是脚注的具体内容。
7. 字体样式
- 加粗：使用双星号
**包围文本。 - 斜体：使用单星号
*包围文本。 - 下划线：使用双下划线
__包围文本。 - 代码：使用反引号
`包围文本。
示例：
**加粗**
*斜体*
__下划线__
`代码`
8. 链接
- 内部链接：指向同一文档中的其他部分。使用
_后跟目标标题。 - 外部链接：指向互联网上的资源。使用URL和可选的显示文本。
示例：
内部链接：参见 :ref:`section-name`。
外部链接：访问 `Python官网 `_。
9. 图片插入
使用.. image::指令插入图片，并可以设置图片的属性，如宽度、高度和替代文本。
示例：
.. image:: images/example.png
:width: 200px
:height: 200px
:alt: 示例图片
10. 特殊字符的处理
特殊字符可以通过反斜杠\进行转义。
示例：
星号 * 不会被解释为斜体。
11. 注释
使用..开始一行来添加注释，这些注释不会出现在最终的输出文档中。
示例：
这是正文。
.. 这是一条注释，不会出现在最终文档中。
12. 简单示例文档创建
以下是一个简单的reStructuredText文档示例，包含了上述所有基本语法元素。
示例文档
================
简介
----
这是一个简单的reStructuredText文档示例。它展示了如何使用各种基本语法元素。
段落与换行
----------
这是一个段落。这是同一段落的另一行。
这是另一个段落。
列表
----
无序列表：
- 项目1
- 项目2
- 项目3
有序列表：
6. 项目1
7. 项目2
3. 项目3
表格
----
+--------+--------+--------+
| 列1 | 列2 | 列3 |
+========+========+========+
| 数据1 | 数据2 | 数据3 |
+--------+--------+--------+
| 数据4 | 数据5 | 数据6 |
+--------+--------+--------+
引用块
------
这是一个引用块：
::
这是引用的内容。
可以包含多行。
字体样式
--------
**加粗**
*斜体*
__下划线__
`代码`
链接
----
内部链接：参见 :ref:`section-name`。
外部链接：访问 `Python官网 `_。
图片插入
--------
.. image:: images/example.png
:width: 200px
:height: 200px
:alt: 示例图片
特殊字符
--------
星号 * 不会被解释为斜体。
注释
----
.. 这是一条注释，不会出现在最终文档中。