reStructuredText语法完全指南

引言

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

基础语法

标题和子标题

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

==================
一级标题（Section）
==================
 
------------------
二级标题（Subsection）
------------------

段落和文本格式

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

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

强调和内联标记

• 加粗：使用两个星号或下划线将文本包围起来。

  **加粗文本** 或 __加粗文本__
  

• 斜体：使用一个星号或下划线将文本包围起来。

  *斜体文本* 或 _斜体文本_
  

列表

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

• 无序列表：使用星号、加号或减号作为列表项的标记。

  * 项目1
  * 项目2

• 有序列表：使用数字和句点作为列表项的标记。

  1. 第一个项目
  2. 第二个项目

引用和注释

• 引用：使用.. note::、.. warning::等指令来创建引用。

  .. note:: 这是一个注意事项。
  

• 注释：使用..和一个空格开始，后面跟着注释内容。

  .. 这是一个注释
  

代码块和语法高亮

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

.. code-block:: python
 
    def hello_world():
        print("Hello, world!")

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

高级特性

超链接和交叉引用

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

• 外部链接：

  `链接文本 `_
  

• 内部链接（交叉引用）：

  :ref:`my-reference-label`
  

图片和图表

• 插入图片：

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

• 创建图表：

  .. graphviz::
   
     digraph foo {
       "bar" -> "baz";
     }

表格

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

• 简单表格：

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

• 网格表格：

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

自定义角色和指令

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

• 自定义角色：

  :myrole:`text`
  

• 自定义指令：

  .. mydirective:: argument
     :option: value
   
     Directive content.

实用案例

文档生成与Sphinx

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

• 自动API文档生成：

  .. automodule:: my_module
     :members:

• 包含外部文件：

  .. include:: external_file.rst
  

学习资源