1   ReStructuredText介绍

Author:eonwen
Contact:eonwen@hotmail.com

下面的文本指向包含类似 快速开始 的链接。这些链接指向 快速开始 用户手册。如果链接无效，请点击 主要快速参考 文档。

注解

该文档是对reStructuredText的一个非正式介绍。下面的 接下来 链接向更进一步的资源，包含一个正式的手册。

1.1   结构

“结构化文本”这个名字可能有点使用不当。其更像是使用特定统一模式的”无拘束文本”。这些模式由一个HTML转换器解释并生成可以被浏览器使用的”非常结构化的文本”。

可以识别的最基本的模式为 段落 ( 跳转 )。它是使用空行分隔的一大块文本(一块就够了)。段落必须保持相同的缩进 – 行始于其左边。段落以缩进开始可能成为缩进引用的段落。如:

This is a paragraph.  It's quite
short.

   This paragraph will result in an indented block of
   text, typically used for quoting other text.

This is another one.

结果是:

This is a paragraph. It’s quite short.

This paragraph will result in an indented block of text, typically used for quoting other text.

This is another one.

1.2   文本样式

( 跳转 )

在段落和其它文本正文中，你可以使用”*italics*“将文本额外标记为 斜体 或使用”**bold**“标记为 粗体 。这被称为”行内标记”。

如果你需要某些东西来显示固定空格文本，使用”``double back-quotes``“。注意，在双反引号里面的内容不会被解析，因此”*“等被保留。

如果你想在文本中使用一个特殊字符，也是可以的 – reStructuredText是相当聪明的。例如，这个单独的星号 * 处理的就很好，就想在等式中的星号：5*6=30。如果你实际需要的是*星号包围*的文本而 不 被斜体，那么你需要通过前置一个反斜杠来表示星号并非特殊字符，像这样”\*“( 跳转 )，或使用两个反引号来封闭它(行内文本)，像这样:

``*``

小技巧

将行内标记想象成(圆括号)的一种形式并以相同的方式使用它：紧跟在被标记的文本之前和之后。行内标记本身（被空白包围）或在一个单词中间无法被识别。详见 标记规范 。

1.3   列表

列表项有三种主要的形式: 有序 、 无序 和 定义 。在所有形式的列表中，你想要多少段落、子列表等等都可以，只要在段落的左边或其与列表项文本第一行对齐都就行。

列表必须要以一个新的段落开始，即它们必须在空行之后。

有序 列表（数字、字母或罗马数字； 跳转）。

以数字或字母之后根一个圆点、右括号或被括号包围。以下所有的形式都可以识别:

1. 数字

A. 小写字母
   可以有多行

   可以有几个段落。

a. 小写字母

   3. 以不同的数字开始的子列表
   4. 确保数字的顺序是对的

I. 大写罗马数字

i. 小写罗马数字

(1) 又是数字

1) 还是数字

结果(注意：不同的有序列表形式不是所有的浏览器都支持，因此你可能无法获得全部效果):

  1. 数字

  1. 小写字母 可以有多行

    可以有几个段落。

  1. 小写字母
    1. 以不同的数字开始的子列表
    2. 确保数字的顺序是对的
  1. 大写罗马数字
  1. 小写罗马数字
  1. 又是数字
  1. 还是数字

无序 列表

类似有序列表，以无序字符开启一行 - 可以是 “-“、”+”或”*”:

* 无序点使用 "*"

  - 一个子列表使用"-"

    + 另一个子列表

  - 另一个列表项

结果:

  • 无序点使用 “*”
    • 一个子列表使用”-“
      • 另一个子列表
    • 另一个列表项

定义 列表

不像其他两个，定义列表包含一个术语和术语的定义。定义列表的格式为:

是什么
  定义列表将一个术语联系到一个定义。

*怎么样*
  术语是一个一行句子，定义是一行或多行段落或正文元素，以缩进联系到术语。
  术语和定义之间不能有空行。

结果:

是什么
定义列表将一个术语联系到一个定义。
怎么样
术语是一个一行句子，定义是一行或多行段落或正文元素，以缩进联系到术语。 术语和定义之间不能有空行。

1.4   预格式化(代码样本)

( 跳转 )

想只包含一块预格式化的永远不被修改的文本，以”::“结束之前的段落。当文本回到与预格式化块之前的段落相同的缩进级别时，预格式化块结束。例如:

一个例子::

    空格、新行、空行和所有类型的标记
      （类似 *this* 或 \this）由文本块保留。
  看看这里，我丢弃了一个缩进级别
  (但依然不够)

例子结束

结果:

一个例子:

  空格、新行、空行和所有类型的标记
    （类似 *this* 或 \this）由文本块保留。
看看这里，我丢弃了一个缩进级别
(但依然不够)

例子结束

注意：如果一个段落仅包含”::“，那么它会在输出时移除:

::

    这是与格式化文本，后面的
    "::"段落被移除了

结果:

这是与格式化文本，后面的
"::"段落被移除了

1.5   章节

( 跳转 )

为了将长文本拆解成章节，你需要使用 章节标题 。这是有装饰的一个单行文本（一个或多个词语）：只有下划线或下划线和上划线一起。可以是”-----“、”======“、”~~~~~~“或任何你认为合适的非字母字符``= - ` : ‘ ” ~ ^ _ * + # < >``。只有下划线装饰的与上下划线使用相同字符装饰的实际上是一样的。上划线/下划线至少要与标题文本一样长。所有拥有相同装饰风格的章节具有相同的级别:

第一章标题
==========

1.1 节标题
----------

1.1.1 小节标题
~~~~~~~~~~~~~~

1.2 节标题
----------

第二章标题
==========

结果为如下结构，简化的伪XML:

<section>
    <title>
        Chapter 1 Title
    <section>
        <title>
            Section 1.1 Title
        <section>
            <title>
                Subsection 1.1.1 Title
    <section>
        <title>
            Section 1.2 Title
<section>
    <title>
        Chapter 2 Title

(伪XML使用缩进来嵌套且没有结束标记。类似另一个例子，它不可能实际处理输出，因为章节不能存在于引用块中。正确的例子，查看本文档的源文本的结构和输出。)

注意：章节标题是一个可用的链接，使用它们的名字就行了。要链接到 列表 标题，只要输入”列表_“即可。如果标题中含有空格，如 文本样式 ，我们需要引用该标题 “`文本样式`_”.

1.5.1   文档标题/子标题

整个文档的标题与章节标题不同且可能以不同的方式格式化(如，HTML writer默认将其展示位一个居中标题)。

在reStructuredText中展示文档标题，在文档开头使用一个唯一的装饰风格。展示文档子标题，使用另一种唯一装饰风格紧跟在文档标题之后。例如:

================
 Document Title
================
----------
 Subtitle
----------

Section Title
=============

...

注意，上面的”文档标题”和”章节标题”都使用了等号，但是是有区别且无关的风格。上下划线标题的文本(并不只有下划线)可以为了美观而插入。

1.6   图片

(跳转)

想要在你的文档中包含一个图片，使用 image 指令. 例如:

.. image:: images/biohazard.png

结果是:

../../_images/biohazard.png

images/biohazard.png 展示了你需要在文档中显示的图片的文件名。对图片（格式、尺寸等）没有限制。如果图片需要展示在HTML中，且你希望提供额外的信息，你可以:

.. image:: images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: alternate text

详见 图片指令文档 。

1.7   接下来

本介绍介绍了reStructuredText最常用的功能，但还有更多功能需要探索。 reStructuredText快速开始 用户手册有助于继续学习。需要完整的细节，详见 reStructuredText标记规范 [1] 。

对于Docutils或reStructuredText有问题或需要帮助的用户，可以发送邮件到 Docutils-users邮件列表 。

[1]如果该链接无效，试试主文档: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.