目录

目录很简单，只要一句:

.. contents::

注意： .. contents:: 要重起一段，并且行前不能有空格。

效果请看上边的目录。

基本文本格式

粗体、斜体及上标和下标表示： 代码:

**用两组星号把我包起来，我就是粗体表示。注意紧接着星号的不能是不可见字符哟！**
*用一组星号把我包起来，我就是斜体表示*
我有一个上标\ :sup:`我是上标`
我有一个下标\ :sub:`我是下标`
上标和下标要用反引号包起来,
并且在:sup:`我是上标`的两边不能有中文字符。
如果需要，可以下面提到的反斜杠加一个英文空格来实现

效果:

用两组星号把我包起来，我就是粗体表示。注意紧接着星号的不能是不可见字符哟！

用一组星号把我包起来，我就是斜体表示

我有一个上标^我是上标

我有一个下标_我是下标

上标和下标要用反引号包起来,

并且在:sup:`我是上标`的两边不能有中文字符。

如果需要，可以下面提到的反斜杠加一个英文空格来实现

表示特殊字符 代码:

表示特殊字符的方法:
使用反斜杠"\"，如　\*星号还在，我不会变成斜体的\*。
这里的反斜杠只是起一个转意的作用，不会显示的。
显示反斜杠\\。
反斜杠还有一个作用，就是取消显示空格。
适用于解决两组特殊字符同时使用时引起的冲突。如:
*re*\ **Structed**\ :sup:`Text`

效果:

表示特殊字符的方法:

使用反斜杠""，如　*星号还在，我不会变成斜体的*。

这里的反斜杠只是起一个转意的作用，不会显示的。

显示反斜杠\。

反斜杠还有一个作用，就是取消显示空格。

适用于解决两组特殊字符同时使用时引起的冲突。如:

reStructed^Text

.. _隐藏的内容:

这个方块里面的东西，是第一版漏了的一点内容。正好用来举\ 内部链接_\ 的例子。
如果想让字符阴影显示，则可以使用双反引号来把内容包起来。比如: ``中文字符``

显示效果如下：

这个方块里面的东西，是第一版漏了的一点内容。正好用来举内部链接的例子。

如果想让字符阴影显示，则可以使用双反引号来把内容包起来。比如： 中文字符

文本 结构

最基本的文本结构应该就是段了。在RST中，段是由空白行来划分的。即两个段之间，至少要有一个空白行。

代码:

我是第一小段的开始，
我不是第二小段的开始哟，我还属于第一小段。字太少了，体现不出区别来。我是在凑字数。我就是被凑出来的。

我才是真正的第二小段。

 看见了吗？我是第三小段，我多缩进了一个空格，显示起来，我就成了一个子段。这个功能可以用来做列表。

效果:

我是第一小段的开始， 我不是第二小段的开始哟，我还属于第一小段。字太少了，体现不出区别来。我是在凑字数。我就是被凑出来的。

我才是真正的第二小段。

看见了吗？我是第三小段，我多缩进了一个空格，显示起来，我就成了一个子段。这个功能可以用来做列表。

列表

项目列表有三种风格: 枚举型, 要点型 和 **定义型**。所有的列表类型中, 可以有任意多的子段落、子列表等，直至段落或者其他的左边和列表项中文本的第一行对齐。

列表必须从一个新的段落开始 -- 也就是说，必须在一个空行后出现。

下面分别介绍三种列表类型:

枚举型 列表(以数字, 字母或者罗马数字打头)

以数字和字母开始，其后紧跟一个"."、右括号")"或者被括号包围"( )" -- 不论喜欢哪种都有。

下面所有的的形式都可被识别(原始格式表示):

1. 数字

A. 大写字母
    而且使用多行

    并且同时有两个段落!

B. 又是大写字母
    多个段落

    紧接一行

a. 小写字母

  3. 有一个使用不同数字的子清单
  4. 可是要确保数字使用正确的顺序!


I. 大小的罗马数字

i. 小写的罗马数字

(1) 数字加括号

1) 数字加半括号

结果是(注意: 这些不同的枚举型列表并不是总被每个浏览器支持，因此你可能不能在这里得到最理想的效果):

1. 数字

1. 大写字母

   而且使用多行

   并且同时有两个段落!

2. 又是大写字母

   多个段落

   紧接一行

1. 小写字母

3. 有一个使用不同数字的子清单
4. 可是要确保数字使用正确的顺序!

1. 大小的罗马数字

1. 小写的罗马数字

1. 数字加括号
2. 数字加括号2

1. 还是数字加半括号

从上面的例子可以发现，如果列表打头的是大写字母，情况比较诡异，请慎用。

要点型 列表

就像枚举型列表一样，也使用一个符号开始------ "-", "+" 或 "*"之一，后面加一个半角空格，再后面要点内容。

代码如下:

* 使用要点符 "*"

 - 使用"-"的子列表

   + 也是一个子列表

 - 另外一项

   + 我也加一个子列表

结果是:

• 使用要点符 "*"

• 使用"-"的子列表
  • 也是一个子列表
• 另外一项
  • 我也加一个子列表

当然上面三种符号的顺序不是特定的。每个符号都可以做为项层标号、中层标号和底层标号。**甚至每层的符号都可以随便使用**，只是在编辑的时候，比较容易搞乱层次。如下面的例子：

代码如下:

- 我以“-”号打头，我是顶层

 + 我以"+"号打头，我是第二层

  * 我以“*”号打头，我是第三层

 - 我以“－”号打头，我是第二层，其实我应该是第一层的，显示起来不会有问题。但是编辑文档的时候会容易搞乱层次。如果达不到色即是空的境界，还是不要用吧。

结果是：

• 我以“-”号打头，我是顶层

• 我以"+"号打头，我是第二层

• 我以“*”号打头，我是第三层

• 我以“－”号打头，我是第二层，其实我应该是第一层的，显示起来不会有问题。但是编辑文档的时候会容易搞乱层次。如果达不到色即是空的境界，还是不要用吧。

定义型 列表如下：

不象前面两个, 定义型列表包括一个术语, 和术语的定义。定义型的格式是:

是什么
  定义型的列表把术语和其定义关联。

*怎么做*
  这个术语是一个单行的词组, 定义是一个或者多个相对术语缩进的段落或者正文元素。

  术语和定义之间不允许有空行。如果有空行，就会就成一个小段和它的子段

结果如下:

是什么

定义型的列表把术语和其定义关联。

怎么做

这个术语是一个单行的词组, 定义是一个或者多个相对术语缩进的段落或者正文元素。

术语和定义之间不允许有空行。如果有空行，就会变成一个小段和它的子段。

章节

你可以使用**章节标题**把很长文本断开为多个章节。他们是一个单行文本（一个或者多个词），但是附带了修饰:

只有一个下标线、或同时有一个下标线和上标线；

他们可使用破折号"-----", 等号"======", 波浪号"~~~~~~" 或者任何其他你喜欢的非字母的字符 = - ` : ' " ~ ^ _ * + # < > 。

一个下标线修饰和使用相同字符的上/下标线修饰区别很明显。

上标线和下标线至少要和文本的长度相同。

他们是一致的，因为所有使用相同修饰风格的章节被认为处于相同的级别(译者：如果出现新的修饰风格，则表示降低一级标题):

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

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

第1.1.1子节 标题
~~~~~~~~~~~~~~~

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

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

结果是(由于例子会打乱文档的结构，这里使用了效果截图):

注意如果想在文档的其他地方链接到某一个标题，只需要使用这些标题的名称引用即可。

如：要链接到 列表 节, 可以使用:

列表_

效果如下:

列表

如果标题中有一个空格如 文本 结构 我们需要使用把标题加反引号如:

`文本 结构`_

效果如下：

文本 结构

注意，这里的链接并不要求另起一行，可以夹在正文中间。另外，有空格的这种引用主要是针对英文的，中文一般不需要加空格。

================
 文档标题
================
----------
 子标题
----------

章节标题
=============

...

图片

在rst文档中显示图片的代码为:

.. image:: 文件名
如: .. image:: logo.jpg (显示上传到wiki文档的图片)
    .. image:: http://www.pku.edu.cn/images/index/3_02.gif  (显示其他网页图片)
这种显示方式为直接显示，如果要rst要转化为html显示，则还有其他一些选项。
如:
.. image:: http://plone.org/logo.jpg
  :height: 100 (高度)
  :width: 200  (宽度)
  :scale: 50    (比例必须要和高度和宽度一起用)
  :alt: 替换文本  (鼠标放到图片上后，显示的字符)

比如下面的例子:

原格式(上传图片)：
 .. image:: logo.jpg
原格式(链接引用)：
 .. image:: http://www.pku.edu.cn/images/index/3_02.gif
设置格式(设置高度为100，宽度为200)：
 .. image:: http://www.pku.edu.cn/images/index/3_02.gif
   :height: 100
   :width: 200
   :alt: 北京大学
设置格式(设置高度为100，宽度为200，显示比例为200％)：
 .. image:: http://www.pku.edu.cn/images/index/3_02.gif
   :height: 100
   :width: 200
   :scale: 200
   :alt: 北京大学

图片显示如下：

原格式(上传图片)：

原格式(链接引用)：

设置格式(设置高度为100，宽度为200)：

设置格式(设置高度为100，宽度为200，显示比例为200％)：

原始格式

如果希望屏蔽一个较长的段落中所有特殊格式，即希望使用些段落的原始格式输出， 则可让前面的段落以"::"结尾。原始块在文本达到到其前一段落相同的缩进后结束。例如:

代码如下:

一个示例::

   空格, 新行, 空行, 和各种标记(如 *这个* 或 \这个)
      都在文本块种保留.
 看这里, 我把缩进降级了
 (但还不够远)

例子结束

结果如下:

一个示例:

 空格, 新行, 空行, 和各种标记(如 *这个* 或 \这个)
    都在文本块种保留.
看这里, 我把缩进降级了
(但还不够远)

例子结束

注意，如果一个段落仅仅包括"::", 就不会再显示:,太人性化了。

代码如下:

::

 这是一个原始文本, 上面
 的"::" 段落将被去除

结果是:

这是一个原始文本, 上面
的"::" 段落将被去除。

超链接

我在这里使用一个外部链接，它指向 北京大学_ 。我也指向 北京大学_ 。大家都指向 北京大学_ 没意思，我指向 seforge_ 。

.. _北京大学: http://www.pku.edu.cn

.. _seforge: http://www.seforge.org

这样使用\ `hello pku`_

.. _hello pku: http://www.pku.edu.cn

我想指向\ 超链接_\ 部分。

我想指向一个地方，这个地方叫\ 隐藏的内容_\ 。定义的举例在别的地方。

如，[百科简介]

如，[我不存在]

表格

下面简单介绍一下，表格的实现。

一般表:

+------------+------------+-----------+
|  表  头  1  | 表 头   2   | 表 头  3   |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

效果如下(由于中文字和英文字母所占长度不合比例，导致表格对中文的支持不好，这里把中文换成拼音了):

简单表:

=====  =====  ======
   输入         输出
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

简单表效果如下：

后续是什么?

这里对新结构化文本的最常用功能进行了简单的介绍，但是仍然还有很多功能需要探索。 新结构化文本快速参考 用户参考是一个下面很好的一个去处。要得到更加完整的详细信息， 新结构化文本标记规范 是应该去的地方 [1].