8. 用reStructuredText编写文档¶
| Page Status: | Development |
|---|---|
| Last Reviewed: |
reStructuredText是一个纯文本的标记语言，可被用于python内嵌文档编写，网页编写或者用来写文章。
Python库docutils实现了对reStructuredText标记语言的解析支持，并能将其转化成其他常用的文档格式，如HTML，Latex，PDF
注解
reStructureText参考资料：
8.1. reStructuredText标记¶
8.2. reStructuredText标记内嵌注意¶
当在文本中使用reStructuredText的标记和对单独词组使用reStructuredText的标记有所不同，需要有一些特别的注意点。见 reStructuredText内嵌语法
- 起始reStructuredText标记之前必须是：
- 空格
- ASCII字符 - : / ‘ ” < ( [ {
- a non-ASCII punctuation character with Unicode category Pd (Dash), Po (Other), Pe (Close), Pf (Final quote), or Pi (Initial quote)
- 起始reStructuredText标记之后必须是一个非空格字符
- 结尾reStructuredText标记之后必须是：
- 空格
- ASCII字符 - : / ‘ ” < ( [ {
- a non-ASCII punctuation character with Unicode category Pd (Dash), Po (Other), Pe (Close), Pf (Final quote), or Pi (Initial quote)
- 结尾reStructuredText标记之前必须是一个非空格字符
- 如果起始起始reStructuredText标记之前有ASCII字符 ‘ ” < ( [ {或者a character with Unicode character category Ps, Pi, or Pf则之后不能直接接ASCII字符’ ” ) ] } > or the categories Pe, Pf, or Pi
- 起始reStructuredText标记和结尾reStructuredText标记之间至少有一个字符
- 反斜杠字符会取消reStructuredText标记的语义
8.3. reStructuredText常见语法¶
8.3.1. 链接相关语法¶
| 语法 | 输出 | 说明 | ||
| `python <http://www.python.org>`_ | python | 内嵌外部链接 | ||
|
pypi_ .. _pypi: https://pypi.python.org/pypi |
pypi | 外部链接1 | ||
|
`python docs`_ .. _`python docs`: http://docs.python.org |
python docs | 外部链接2 | ||
|
`python intro`_ .. _`python intro`: python introducation |
python introducation |
内部链接 | ||
|
`anonymous`__ __ http://www.python.org/ |
anonymous | 匿名链接 | ||
|
[1]_ .. [1] this is a footnote |
|
脚注 | ||
|
[citation]_ .. [citation] this is a citation |
|
引用 |
8.3.2. 段落相关语法¶
8.3.2.1. 普通段落¶
| 语法 | 输出 | 说明 |
|
This is a paragraph. Paragraphs line up at their left edges, and are normally separated by blank lines. |
This is a paragraph. Paragraphs line up at their left edges, and are normally separated by blank lines. |
段落以空行分隔 |
8.3.2.2. 标题¶
| 语法 | 输出 | 说明 |
|
parts ########### chapters *********** sections ========= subsections ------------ subsubsections ^^^^^^^^^^^^^^^ paragraphs """"""""""""" |
partschapterssectionssubsectionssubsubsectionsparagraphs |
标题由底部（或底部和顶部）连续的一组ASCII非字母数字的字符标识， 标题级别自动分配，最先出现的标题级别较高， 推荐使用标识字符有"= - ` : ' " ~ ^ _ * + # < >"。 Sphinx推荐在python文档中使用如下的规则： |
8.3.2.3. 列表¶
列表的开始和结束各需要一个空行，列表中间的空行是可有可无的
| 语法 | 输出 | 说明 | ||||||||||
|
- This is item 1 - This is item 2 |
|
Bullet Lists | ||||||||||
|
3. This is the first item 4. This is the second item 5. Enumerators are arabic numbers, single letters, or roman numerals 6. List items should be sequentially numbered, but need not start at 1 (although not all formatters will honour the first index). #. This item is auto-enumerated |
|
Enumerated Lists | ||||||||||
|
what Definition lists associate a term with a definition. how The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition. |
|
Definition Lists | ||||||||||
|
:Authors: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) :Version: 1.0 of 2001/08/08 :Dedication: To my father. |
Authors: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) Version: 1.0 of 2001/08/08 Dedication: To my father. |
Field Lists | ||||||||||
|
-a command-line option "a" -b file options can have arguments and long descriptions --long options can be long also --input=file long options can also have arguments /V DOS/VMS-style options too |
|
Option Lists |
8.3.2.4. 文字块¶
注解
文字块中的特殊字符不会被解析和替代， 所有的特殊字符，空格和换行符会被保留。
| 语法 | 输出 | 说明 |
| ``内嵌文字块`` |
内嵌文字块 |
内嵌块经常用于显示一段短小的代码 |
|
只有双引号``::``的段落表明接下来的所有缩进的/引用的文字都是一个文字块 :: 所有的reStructureText的转义字符如空格，换行，空行 (like *this* or \this) 都不会被转义，会被直接保留。 结果中不会保留双引号 双引号``::``可以位于一个段落的最后， 如果双引号``::``后面接空格，双引号会被忽略， 如果双引号``::``后面接文字，双引号会变成一个单引号， 比如:: 这样很方便 当缩进恢复正常，文字段结束， 所以我们可以在文字段中使用不同的缩进:: 8个空格的缩进 4个空格的缩进 2个空格的缩进 也使用引用来标识文字块，合法的引用符号有:: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ 利用引用标识的文字块示例:: > 引用的文字块第一行 > 引用的文字块第二行 |
只有双引号``::``的段落表明接下来的所有缩进的/引用的文字都是一个文字块 所有的reStructureText的转义字符如空格，换行，空行 (like *this* or \this) 都不会被转义，会被直接保留 结果中不会保留双引号 双引号``::``可以位于一个段落的最后 如果双引号``::``后面接空格，双引号会被忽略 如果双引号``::``后面接文字，双引号会变成一个单引号 比如: 这样很方便 当缩进恢复正常，文字段结束 所以我们可以在文字段中使用不同的缩进:
8个空格的缩进
4个空格的缩进
2个空格的缩进
也使用引用来标识文字块，合法的引用符号有：
! " # $ % & ' ( ) * + , - . / : ;
< = > ? @ [ \ ] ^ _ ` { | } ~
利用引用标识的文字块示例: > 引用的文字块第一行 > 引用的文字块第二行 |
段落块 两个冒号加一个空行后面所有的缩进的段落都是块 |
|
| Line blocks are useful for addresses, | verse, and adornment-free lists. | | Each new line begins with a | vertical bar ("|"). | Line breaks and initial indents | are preserved. | Continuation lines are wrapped portions of long lines; they begin with spaces in place of vertical bars. |
Line blocks are useful for addresses, verse, and adornment-free lists. Each new line begins with a vertical bar ("|"). Line breaks and initial indents are preserved. Continuation lines are wrapped portions of long lines; they begin with spaces in place of vertical bars. |
行块 |
8.3.2.5. 注释¶
没有有效标记(如脚注)的直解标记(.. )文本块就是注释(参考) 例如:
可以用缩进文本来进行多行注释:
..
This whole indented block
is a comment.
Still in the comment.
注解
注释内容在输出中可能不可见
8.3.2.6. 代码块¶
可以用如3.2.4节文字块的方法来标识代码块:
示例：
python code::
#python code
def one_function():
pass
输出：
python code:
#python code
def one_function():
pass
8.3.4. 指令语法¶
指令是reStructuredText用来在不改变/新增已有语法的基础上，扩展新的特性的一种机制。
reStructuredText标准指令文档 罗列了所有的标准指令
其他的指令由各自的解析器自己定义，比如sphinx就支持很多 自定义的指令
指令语法示意:
+-------+------------------+
| ".. " | 指令类型 "::" 指令 |
+-------+ 块 |
| |
+------------------+
指令块由指令符后面所有缩进内容组成，指令块可以包含三部分：
- Directive arguments
- Directive options
- Directive content
Directive arguments和Directive options紧接着指令。Directive content和它们之间用空行分隔。
不同的指令对指令块的要求不同，如果提供的指令块不符合要求，会导致错误
下面介绍一些常用的标准指令和sphinx扩充的指令。
8.3.4.1. reStructuredText标准指令¶
8.3.4.1.1. 提醒指令¶
提醒指令 ，包含”attention”, “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, “warning”, “admonition”
示例:
.. attention::
Attention Please!
输出 ：
注意
Attention Please!
8.3.4.1.2. image指令¶
图片指令 向输出中插入指定图片
示例:
.. image:: images/happy_dog.jpg
:heigsht: 200px
:width: 300 px
:scale: 50 %
:alt: 快乐的狗狗
输出 ：
8.3.4.1.3. role指令¶
role指令 建立并向解析器注册了role类型，所有mark成这种role类型的文本都会被解析器以这种类型解析。
reStructureText定义了一些 标准role类型
sphinx也扩充了 一些role类型
自定义role类型示例 ：
使用role指令动态定义一种文本解析方式:
.. role:: custom
文本中使用custom类型的文本会被按照custom类型来解析:
An example of using :custom:`interpreted text`
结果会类似于这样:
<paragraph>
An example of using
<inline classes="custom">
interpreted text
注解
role指令必须先定义，再使用
基于已有role类型的示例:
可以基于已有的role类型来定义新的role类型，新的role类型将是已有类型的一个子集
定义:
.. role:: raw-role(raw)
:format: html
使用:
用html实现 :raw-role:`<strong>加粗的文本</strong>`
输出：
用html实现 加粗的文本
8.3.4.2. sphinx扩充的指令¶
sphinx对reStructureText的指令有所扩充，见 Sphinx Markup Constructs