3. 样例¶

本节内容

3.1. 标题 ¶

一级标题
========

二级标题
--------

三级标题
~~~~~~~~

四级标题
^^^^^^^^

注解

中文占两个字符宽度。标题和标记并不强制要求对齐。

也可以用以下的形式:

====
标题
====

3.2. 段落 ¶

段落不需要特殊标记，有缩进的段落生成的结果也会有缩进。

段落用一个空行隔开，换行只会产生一个空格。

源码:

第一段
换行

第二段

    缩进第一段

    缩进第二段

结果:

第一段换行

第二段

缩进第一段

缩进第二段

3.3. 文字强调 ¶

源码	结果
`支持对\ 文字\ 的\ 强调`	支持对文字的强调
`emphasis and strong emphasis`	emphasis and strong emphasis

注解

中文问题

reStructuredText的特殊标记一般需要两侧是空格或者行首末，英文用空格隔开单词，所以不需要作特殊处理。

而中文则很可能需要两侧添加\空格。

3.4. 图片 ¶

源码	结果
`.. image:: images/ball1.gif`
`.. image:: http://www.w3schools.com/images/pulpit.jpg`

注解

路径相对于conf.py所在目录。生成的PDF不支持外链图片。

3.5. 链接 ¶

源码	结果
http://example.com	http://example.com
This is a `link <http://example.com>`_	This is a link
这是一个\ `链接 <http://example.com>`_	这是一个链接
这也是一个\ `链接`_，\ `另一个链接`_ .. _`链接`: http://example.com .. _`另一个链接`: http://example2.com	这也是一个链接，另一个链接

注解

当一段文字里有大量超链接时，推荐使用上面表格里最后一种方式。

3.6. 引用 ¶

3.6.1. Line-blocks ¶

| line-blocks
| *line-blocks*

line-blocks

line-blocks

3.6.2. Literal-blocks ¶

::

    literal-blocks
    *literal-blocks*

literal-blocks
*literal-blocks*

3.7. 脚注(Footnote)¶

正文\ [#脚注]_

正文[1]

3.8. 代码段 ¶

3.8.1. ruby代码样例 ¶

.. code-block:: ruby

   #!/usr/bin/ruby
   ...

#!/usr/bin/ruby
class Person
  attr_reader :name, :age
  def initialize(name, age)
    @name, @age = name, age
  end
  def <=>(person) # Comparison operator for sorting
    age <=> person.age
  end
  def to_s
    "#{name} (#{age})"
  end
end

# 中文注释
group = [
  Person.new("Bob", 33),
  Person.new("Chris", 16),
  Person.new("Ash", 23)
]

puts group.sort.reverse

3.8.2. java代码样例 ¶

.. code-block:: java

   // Hello.java
   ...

// Hello.java
import java.io.*;
import javax.servlet.*;

public class Hello extends GenericServlet {
    public void service(final ServletRequest request, final ServletResponse response)
    throws ServletException, IOException {
        response.setContentType("text/html");
        final PrintWriter pw = response.getWriter();
        try {
            pw.println("Hello, world!");
        } finally {
            pw.close();
        }
    }
}

注解

有缩进的都会被认为是代码段，可以用..显式标明代码结束位置:

.. code-block:: java

   // Hello.java
   ...

..

3.9. 列表 ¶

3.9.1. 无序列表 ¶

* 第一项

  第一项说明

  * 子项
  * 子项

* 第二项

      第二项说明(有缩进)

第一项

第一项说明
- 子项
- 子项
第二项

第二项说明(有缩进)

3.9.2. 有序列表 ¶

#. 第一项

   第一项说明

   #. 子项
   #. 子项

#. 第二项

       第二项说明(有缩进)

第一项

第一项说明
1. 子项
2. 子项
第二项

第二项说明(有缩进)

3.10. 表格 ¶

3.10.1. 简单表格 ¶

==== ====
中文 表格
==== ====
测试 测试
测试 测试
==== ====

中文	表格
测试	测试
测试	测试

3.10.2. 网格表格 ¶

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Table cells contain body elements.
body row 4	Cells may span rows.	Table cells contain body elements.

注解

Vim 的rst-tables插件可以辅组表格生成和维护。

默认主题的表格看起来不大对，是因为下面的CSS样式导致的:

table.docutils td, table.docutils th {
  border-style: none none solid;
  border-width: 0 0 1px;
}

3.10.3. 列表表格(List-table)¶

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

Frozen Delights!
Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

3.10.4. 外部表格 ¶

.. csv-table:: 表格描述
   :header: 中文,表格
   :file: table.csv

table.csv:

"测试,测试",测试
测试,测试

表格描述
中文	表格
测试,测试	测试
测试	测试

3.11. 字段列表(Field lists)¶

:词汇: 解释
:词汇: 解释

词汇:	解释
词汇:	解释

3.13. 箴言(Admonitions)¶

.. ATTENTION:: ATTENTION
.. CAUTION:: CAUTION
.. DANGER:: DANGER
.. ERROR:: ERROR
.. HINT:: HINT
.. IMPORTANT:: IMPORTANT
.. NOTE:: NOTE
.. TIP:: TIP
.. WARNING:: WARNING
.. admonition:: 自定义箴言

   箴言内容

注意

ATTENTION

警告

CAUTION

危险

DANGER

错误

ERROR

提示

HINT

重要

IMPORTANT

注解

NOTE

小技巧

TIP

警告

WARNING

自定义箴言

箴言内容

3.14. 替代(Substitution)¶

.. |ball| image:: images/ball1.gif

|ball| |ball|

ball ball

3.15. 内嵌HTML ¶

.. raw:: html

   <p>段落，<a href="http://example.com">链接</a></p>

段落，链接

3.16. 自动生成目录 ¶

在index.rst里添加类似下面的内容，生成的HTML及PDF会自动生成目录:

.. toctree::
   :numbered:
   :maxdepth: 2

   setup
   usage
   demo

章节里用:

.. contents:: 本节内容
   :local:

来插入本章节的目录。

3.17. 锚点跳转 ¶

标题会自动生成锚点，也可以手工创建:

.. _某章节:

正文

:ref:`引用 <某章节>`

具体查看\ `某章节`_

正文

引用

具体查看某章节

注解

英文标题会生成合理的锚点ID，但中文标题只会生成类似#id2这样的锚点。

如果某一章节需要引用，建议手工创建锚点:

.. _custom_id:

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

3.18. CSS样式 ¶

创建source/_static/default.css就可以覆盖内置的样式

[1]

脚注内容

3. 样例¶

3.1. 标题 ¶

3.2. 段落 ¶

3.3. 文字强调 ¶

3.4. 图片 ¶

3.5. 链接 ¶

3.6. 引用 ¶

3.6.1. Line-blocks ¶

3.6.2. Literal-blocks ¶

3.7. 脚注(Footnote)¶

3.8. 代码段 ¶

3.8.1. ruby代码样例 ¶

3.8.2. java代码样例 ¶

3.9. 列表 ¶

3.9.1. 无序列表 ¶

3.9.2. 有序列表 ¶

3.10. 表格 ¶

3.10.1. 简单表格 ¶

3.10.2. 网格表格 ¶

3.10.3. 列表表格(List-table)¶

3.10.4. 外部表格 ¶

3.11. 字段列表(Field lists)¶

3.12. 边栏(Sidebar)¶

3.13. 箴言(Admonitions)¶

3.14. 替代(Substitution)¶

3.15. 内嵌HTML ¶

3.16. 自动生成目录 ¶

3.17. 锚点跳转 ¶

3.18. CSS样式 ¶

內容目录

本页

下载

导航

3. 样例¶

本页

下载

导航