3. 样例¶
本节内容
3.1. 标题¶
一级标题========二级标题--------三级标题~~~~~~~~四级标题^^^^^^^^
注解
中文占两个字符宽度。标题和标记并不强制要求对齐。
也可以用以下的形式:
====标题====
3.2. 段落¶
段落不需要特殊标记，有缩进的段落生成的结果也会有缩进。
段落用一个空行隔开，换行只会产生一个空格。
源码:
第一段换行第二段 缩进第一段 缩进第二段
结果:
第一段换行
第二段
缩进第一段
缩进第二段
3.3. 文字强调¶
| 源码 | 结果 |
|---|---|
| 支持对\*文字*\的\**强调** | 支持对文字的强调 |
| *emphasis*and**strongemphasis** | emphasis andstrong 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 alink |
这是一个\ `链接 <http://example.com>`_ | 这是一个链接 |
这也是一个\ `链接`_，\ `另一个链接`_.. _`链接`: http://example.com.. _`另一个链接`: http://example2.com | 这也是一个链接，另一个链接 |
注解
当一段文字里有大量超链接时，推荐使用上面表格里最后一种方式。
3.8. 代码段¶
3.8.1. ruby代码样例¶
.. code-block:: ruby #!/usr/bin/ruby ...
#!/usr/bin/rubyclassPersonattr_reader:name,:agedefinitialize(name,age)@name,@age=name,ageenddef<=>(person)# Comparison operator for sortingage<=>person.ageenddefto_s"#{name} (#{age})"endend# 中文注释group=[Person.new("Bob",33),Person.new("Chris",16),Person.new("Ash",23)]putsgroup.sort.reverse
3.8.2. java代码样例¶
.. code-block:: java // Hello.java ...
// Hello.javaimportjava.io.*;importjavax.servlet.*;publicclassHelloextendsGenericServlet{publicvoidservice(finalServletRequestrequest,finalServletResponseresponse)throwsServletException,IOException{response.setContentType("text/html");finalPrintWriterpw=response.getWriter();try{pw.println("Hello, world!");}finally{pw.close();}}}
注解
有缩进的都会被认为是代码段，可以用..显式标明代码结束位置:
.. code-block:: java // Hello.java .....
3.10. 表格¶
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 mayspan rows. |
| |
| body row 4 | |||
注解
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!
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t becrunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
3.10.4. 外部表格¶
.. csv-table:: 表格描述 :header: 中文,表格 :file: table.csv
table.csv:
"测试,测试",测试测试,测试
| 中文 | 表格 |
|---|---|
| 测试,测试 | 测试 |
| 测试 | 测试 |
3.12. 边栏(Sidebar)¶
.. sidebar:: 标题 :subtitle: 副标题 边栏内容正文内容
标题
副标题
边栏内容
正文内容，正文内容，正文内容，正文内容，正文内容，正文内容，正文内容
正文内容
正文内容
正文内容
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.16. 自动生成目录¶
在index.rst里添加类似下面的内容，生成的HTML及PDF会自动生成目录:
.. toctree:: :numbered: :maxdepth: 2 setup usage demo
章节里用:
.. contents:: 本节内容 :local:
来插入本章节的目录。
3.17. 锚点跳转¶
标题会自动生成锚点，也可以手工创建:
.. _某章节:正文:ref:`引用 <某章节>`具体查看\ `某章节`_
正文
具体查看某章节
注解
英文标题会生成合理的锚点ID，但中文标题只会生成类似#id2这样的锚点。
如果某一章节需要引用，建议手工创建锚点:
.. _custom_id:章节标题========