Codes►综合

rst用法

rst用法

简单用法

ReStructuredText（RST）是一种用于文档编写的轻量级标记语言，广泛应用于 Python 社区和许多开源项目中，用于编写文档和生成各种格式的文档输出（如 HTML、PDF 等）。RST 的语法简洁明了，易于阅读和编写，同时也能很好地转换为其他格式。
以下是 RST 的一些基本用法：

1. 标题

RST 使用不同数量的下划线或上划线来表示不同级别的标题。

1
2
3
4
5
6
标题 1
======
标题 2
------
标题 3
~~~~~~

2. 段落

段落是文本的基本单位，由一个或多个空行分隔。

1
2
这是一个段落。
这是另一个段落。

3. 强调

RST 提供了多种方式来强调文本。

  • 斜体：使用单个星号 * 包裹文本。
  • 粗体：使用双星号 ** 包裹文本。
  • 下划线：使用单个下划线 _ 包裹文本。
1
2
3
这是一个 *斜体* 文本。
这是一个 **粗体** 文本。
这是一个 _下划线_ 文本。

4. 列表

RST 支持有序列表和无序列表。

  • 无序列表：使用 -、* 或 + 作为项目符号。
  • 有序列表：使用数字后跟一个点 . 或括号 )。
1
2
3
4
5
6
7
8
无序列表：
- 项目 1
- 项目 2
- 项目 3
有序列表：
1. 项目 1
2. 项目 2
3. 项目 3

5. 链接

RST 支持内联链接和引用链接。

  • 内联链接：使用 链接文本 <链接地址> 的格式。
  • 引用链接：使用 链接文本 _ 的格式，并在文档末尾定义链接。
1
2
3
这是一个内联链接： ` 链接文本 <http://example.com> `_
这是一个引用链接： ` 链接文本 `_
.. _链接文本: http://example.com

6. 图片

使用 .. image:: 指令插入图片。

1
2
3
4
.. image:: /path/to/image.png
   :alt: 替代文本
   :width: 400px
   :align: center

7. 代码块

使用 .. code-block:: 指令插入代码块，并指定语言。

1
2
3
.. code-block:: python
   def hello_world():
       print("Hello, World!")

8. 表格

RST 提供了多种表格格式，最常用的是网格表格和简单表格。

  • 网格表格：
1
2
3
4
5
6
7
+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+
  • 简单表格：
1
2
3
4
5
6
7
8
9
10
=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
 True  False   True
False  True   True
 True   True   True
=====  =====  ======

9. 注释

使用 .. 开头的行来创建注释。

1
这是一个注释，不会显示在最终文档中。

10. 引用

使用 .. 指令来引用其他文档或章节。

1
2
3
4
5
.. toctree::
   :maxdepth: 2
   introduction
   installation
   usage

11. 脚注

使用 .. [1] 格式添加脚注。

1
2
这是一个脚注引用 [1]。
.. [1] 这是脚注的内容。

12. 替换

使用 .. |name| replace:: 来定义替换文本。

1
2
.. |version| replace:: 1.0.0
当前版本是 |version|。

示例文档

以下是一个完整的 RST 示例文档：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
标题 1
======
这是一个段落，包含 *斜体* 和 **粗体** 文本。
无序列表：
- 项目 1
- 项目 2
- 项目 3
有序列表：
1. 项目 1
2. 项目 2
3. 项目 3
这是一个内联链接： ` 链接文本 <http://example.com> `_
这是一个引用链接： ` 链接文本 `_
.. _链接文本: http://example.com
.. image:: /path/to/image.png
   :alt: 替代文本
   :width: 400px
   :align: center
.. code-block:: python
   def hello_world():
       print("Hello, World!")
+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+
这是一个注释，不会显示在最终文档中。
这是一个脚注引用 [1]。
.. [1] 这是脚注的内容。
.. |version| replace:: 1.0.0
当前版本是 |version|。

工具

  • Sphinx：一个基于 RST 的文档生成工具，广泛用于 Python 项目的文档编写。
  • reStructuredText Lint：一个用于检查 RST 文档语法的工具。
  • RST Viewer：一个在线工具，可以实时预览 RST 文档的渲染效果。
    希望这些内容能帮助你更好地使用 RST！如果你有更具体的问题或需要进一步的示例，请告诉我。