reStructuredText语法完全指南

引言

在编程和文档编写领域，reStructuredText（简称reST）是一种轻量级的标记语言，广泛应用于Python社群和其他技术社群。与Markdown相比，reST提供了更多的灵活性和功能，特别是在生成高质量的文档和网站时。本文将深入探讨reStructuredText的各种语法和特性，包括基础语法、高级特性、实用案例，以及额外的学习资源。

基础语法

标题和子标题

在reST中，标题和子标题是通过使用不同的装饰字符来创建的。这些字符可以是等号（=）、减号（-）或其他字符。

markdown 复制代码

==================
一级标题（Section）
==================

------------------
二级标题（Subsection）
------------------

段落和文本格式

在reST中，段落是通过空行来分隔的。如果你想在段落内部进行换行，可以使用两个或更多的空格。

复制代码

这是一个段落。

这是另一个段落，  
这里是同一个段落的第二行。

强调和内联标记

加粗：使用两个星号或下划线将文本包围起来。
markdown 复制代码
```
**加粗文本** 或 __加粗文本__
```
斜体：使用一个星号或下划线将文本包围起来。
markdown 复制代码
```
*斜体文本* 或 _斜体文本_
```

列表

reST支持多种类型的列表，包括有序列表和无序列表。

无序列表：使用星号、加号或减号作为列表项的标记。
markdown 复制代码
```
* 项目1
* 项目2
```
有序列表：使用数字和句点作为列表项的标记。
markdown 复制代码
```
1. 第一个项目
2. 第二个项目
```

引用和注释

引用：使用.. note::、.. warning::等指令来创建引用。
arduino 复制代码
```
.. note:: 这是一个注意事项。
```
注释：使用..和一个空格开始，后面跟着注释内容。
复制代码
```
.. 这是一个注释
```

代码块和语法高亮

reST支持多种编程语言的代码块和语法高亮。

css 复制代码

.. code-block:: python

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

这里，python指定了代码块使用的编程语言，以便进行语法高亮。

高级特性

超链接和交叉引用

reST提供了多种创建超链接和交叉引用的方法。

外部链接：
arduino 复制代码
```
`链接文本 <http://example.com>`_
```
内部链接（交叉引用）：
perl 复制代码
```
:ref:`my-reference-label`
```

图片和图表

插入图片：

arduino 复制代码

.. image:: /path/to/image.jpg
   :alt: 图片描述

创建图表：

rust 复制代码

.. graphviz::

   digraph foo {
     "bar" -> "baz";
   }

表格

reST支持多种类型的表格，包括简单表格和网格表格。

简单表格：

diff 复制代码

=====  =====  ======
输入   操作    输出
=====  =====  ======
1      倍乘    2
2      倍乘    4
=====  =====  ======

网格表格：

css 复制代码

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| cell 1     | cell 2     | cell 3    |
+------------+------------+-----------+

自定义角色和指令

reST允许你创建自定义的角色（inline markup）和指令（block-level markup）。

自定义角色：
ruby 复制代码
```
:myrole:`text`
```

自定义指令：

ruby 复制代码

.. mydirective:: argument
   :option: value

   Directive content.

实用案例

文档生成与Sphinx

Sphinx是一个强大的文档生成工具，它使用reST作为标记语言。通过Sphinx，你可以轻松地生成多种格式的文档，包括HTML、PDF、ePub等。

自动API文档生成：
ruby 复制代码
```
.. automodule:: my_module
   :members:
```
包含外部文件：
arduino 复制代码
```
.. include:: external_file.rst
```