13.11. 面向Markdown用户的ReStructured Text指南

你可以将RST视为“Markdown，但更强大”。具体含义如下：

RST基本上和Markdown一样简单
但RST不仅更加精确，还提供了更多可用的格式化结构（而不会变得过于复杂）

The full Sphinx / RST documentation is available here: https://www.sphinx-doc.org/en/master/index.html

如果您熟悉Markdown语法，以下章节将提供一些快速上手RST格式的实用技巧。

13.11.1. 空白与缩进

MD: 在大多数情况下，空白和缩进通常无关紧要。但对于项目符号和子项目符号来说确实很重要，不过规则相当奇怪，并且不同的Markdown渲染器之间会有所不同。
RST: 缩进很重要。非常重要。就像Python一样。一般来说，你需要将所有RST文本缩进以保持在同一层级。例如，所有这些文本将作为一个段落。

空行也很重要。非常重要。你可以使用空行来划分同一缩进级别内的不同部分。例如，本段之前的空行表示段落分隔。
注意

RST由Python社区创建。因此，空格非常重要。
- 缩进很重要
- 内容之间的空行很重要

使用空行和缩进表示前一项的结束。例如，本段落不属于MD/RST项目符号列表的一部分。

13.11.2. 等宽字体

MD: 使用单引号:
```
`hello world`
```
RST: 使用一对单引号:
```
``hello world``
```

13.11.3. 斜体

MD: *hello world* 或 _hello world_
RST: *hello world*

13.11.4. 粗体

MD: **hello world**
RST: 与MD相同

13.11.5. 章节与段落分隔符

MD: 在文本行左侧使用一个或多个井号（#, ##, ###），或者用井号在文本行下方划线
RST: 有一行文本，下方用非ASCII字符加下划线。
- 底层必须至少与文本行一样长
- 底层使用哪种非ASCII字符并不重要，但它们的排列顺序表示章节/小节/子小节等层级关系。
  
  在这些OMPI文档中，我们使用的下划线字符序列如下：
```
第1章：hello world
======================
```
```
第1节：hello world
----------------------
```
```
第1子节：hello world
^^^^^^^^^^^^^^^^^^^^^^^^^
```
```
第1子子节：hello world
++++++++++++++++++++++++++++
```
  含义：由=组成的下划线表示章节，由-组成的下划线表示节，由^组成的下划线表示子节，由+组成的下划线表示子子节。

13.11.6. 多行代码/等宽字体

MD: 使用三个单引号来界定文本块。可选地包含一个标记关键字来指定该代码块内使用的语法高亮。
```
```c
int main() { printf("Hello world\n"); return 0 }
```
```
RST: 使用 .. code-block:: KEYWORD 来开始一个代码段。
```
.. code-block:: c

   int main() { printf("Hello world\n"); return 0 }
```
- KEYWORD 表示要使用哪种语法高亮（例如 c、 c++ make、sh、ini、Fortran、diff、 python、java、rst 等）。
- 如果不使用特定的高亮显示，可以省略KEYWORD。
- 在code-block行之后必须有一个空行。
- 代码块中的行必须缩进到与code-block中第一个c相同的列。例如：
```
.. code-block:: sh

   shell$ tar xf openmpi-.tar.bz2
   shell$ cd openmpi-
   shell$ ./configure --prefix= |& tee config.out
```
  请注意，代码块将渲染在.. code-block::第一个.开始的相同层级。在这个例子中，示例代码块将渲染在项目符号条目中。

而这段文字和代码块将位于上述项目列表之外：

shell$ tar xf openmpi-<version>.tar.bz2
shell$ cd openmpi-<version>
shell$ ./configure --prefix=<path> |& tee config.out

# Fun note: the code-block can contain blank lines.

代码块以空行结束，然后缩进回退到与.. code-block::中第一个.相同的层级。

13.11.7. 无编号项目符号

MD: 行首以 * 或 - 开始
RST: 行首以*开始。可以在相同缩进级别换行，以在同一项目符号下形成段落。

在空行后以相同缩进级别继续输入文本，将在同一项目符号下创建另一个段落。您甚至可以在同一缩进级别放置其他指令。
- 例如，您可以开始一个子项目符号。
  
  这段文字是同一子项目符号中的下一个段落。
```
This is a verbatim code block within this same sub bullet.
More about code-blocks below.
```
  这是同一子项目符号中（代码块之后的）下一个段落。
- 如果开始一个新的项目符号，将终止前一个项目符号。
- 你必须在项目符号之间留空行！

13.11.8. 编号项目符号:

MD: 以 # 开始行
RST格式：行首以#.开始

重要提示

注意：结尾的.符号是必须的

例如：
```
#. 第一条项目
#. 第二条项目
#. 第三条项目
```
所有关于缩进的规则与上述描述保持一致。

13.11.9. 注释

MD: Enclose content in (i.e., HTML comments, but they are included in the output)

RST：以两个点和一个空格开始一行。

例如，以下代码块是一个注释，不会被包含在输出中：

.. Hello world.  This is a comment.  This whole block is a
   comment.  You can leave it here in the final document, and it
   will not be included in the rendered output.

   Your comment can even include blank lines.  You terminate a
   comment |mdash| just like most other things in RST |mdash| by a blank
   line and then outdenting back out to the same column as the
   first ".".

这一行不再是注释的一部分。

13.11.10. 包含文件

MD: 在Markdown中无法包含文件。
RST：使用.. include:: FILENAME指令。例如：
```
.. include:: features-extensions.rst
.. include:: features-java.rst
```
这些指令会将这两个文件直接包含到当前RST文件中。

重要提示

章节/小节分隔符将在这些文件中继续作为渲染本文件的一部分。

13.11.11. 超链接到URL

MD:

[这是链接文本](https://example.com/)

RST格式：
```
`这是链接文本 `_
```
重要提示

是的，RST中结尾的下划线很重要。虽然有点奇怪，但你会适应的。

13.11.12. 指向锚点的超链接

MD：我一时想不起来如何在MD中创建锚点和链接到它们。
RST：使用:ref:指令。

按如下方式创建锚点：
```
.. _ANCHOR_NAME:
```
它必须以下划线开头并以冒号结尾。

我通常使用以label-开头或以-label结尾的锚点名称，使其明显表明这是一个标签。例如：
```
.. _building-and-installing-section-label:
```
然后就可以使用:ref:指令：
```
请务必参阅 :ref:`VPATH构建章节
`。
```

13.11.13. 指向其他(RST)页面的超链接

MD:
```
[链接文本](页面名称)
```
RST：使用:doc:指令。

通用格式：
```
:doc:`链接文本 <页面路径>`
```
例如：
```
您应该阅读:doc:`开发者指南 `。
```
页面路径是相对于OMPI git树中的docs目录。

13.11.14. 宏

MD: Markdown中没有宏。
RST：我们在RST中定义了一些openmpi特有的宏。您可以在RST内容文本的任何位置插入这些宏。
- |ompi_ver| 是完整的Open MPI版本号，包含alpha/beta/rc/greek标识。例如 5.0.0rc1。
- |ompi_series| 表示Open MPI的主/次版本号，例如 5.0.x。
  
  重要提示
  
  在引用当前版本或系列时，请慎重考虑是否要硬编码Open MPI版本号或系列号。硬编码"x.y.0"版本号来表示一个代际时期可能是合适的，但在大多数其他情况下，您可能希望使用其中一个宏。
- |mdash| 是一个Unicode长破折号，即"em"破折号。请使用它来代替 --。
- |rarrow| 是一个 Unicode 右箭头符号。请使用它替代 -> 或 -->。

13.11.15. 色彩鲜艳的方框

MD: MD中没有色彩鲜艳的方框。
RST: 您可以使用各种指令在RST中创建高亮显示的"注意"框（称为警示框）。例如：
重要

一个带有“！”图标的绿色方框

标准缩进规则适用于框内的内容。例如，您可以有多行和多段落。

太好了。
- 你甚至可以使用项目符号。
  你甚至可以在警告框内的项目符号内放置代码块。
- 所有标准的缩进规则均适用。
提示

一个带有“！”图标的绿色方框

注意

一个带有“！”图标的蓝色方框

警告

一个带有“！”图标的橙色方框

注意

一个带有“！”图标的橙色方框

警告

一个带有“！”图标的橙色方框

错误

一个带有“！”图标的红色方框

危险

一个带有“！”图标的红色方框
自定义标题

您可以随意命名此框：
```
.. admonition:: Custom title
   :class: tip

   Content of your box here.
```
本自定义提示框的自定义文本。请注意，:class: 会根据基本提示框类型的配色方案改变颜色。例如，:class: tip会使框体显示为绿色。