reStructuredText 初学者语法汇总
文档格式编辑,目前主流最强大的是LaTeX,但是语法太复杂,环境要求也多,有的时候也是写文档往往选择 Markdown。常常怀疑文档编辑的Markdown不是亲生的, 很多功能不全,而且各个的厂家的语法支持都有比较大的出入,终于找到比Markdown强大的了。reStructuredText只比Markdown复杂一点点,但是功能要强大很多。接下来我就为大家介绍一下reStructuredText的一些语法。
目录
段落
行内标记
列表和“类”引用块
源代码
表格
超链接
外部链接
内部链接
章节
显式标记
指令(标识符)
图片
脚注
引文
替换
评论
源文件编码
陷阱
段落
段落(ref)是reST文档中最基本的块。段落是由一个或多个空白行分离的简单的文本块。在Python中,缩进在reST中是具有重要意义,所以同一段落的所有行必须左对齐而且是同一级缩进。
行内标记
标准的行内标记相当简单:使用
- 单星号: *text* 强调 (斜体),
- 双星号: **text** 重点强调 (粗体),以及
- 反引号: ``text`` 代码示例。
如果星号或反引号出现在文本会对行内标记分隔符引起混淆,他们必须用一个反斜杠进行转义。
注意行内标记一些限制:
- 不能嵌套,
- 文本不能以空格开始或者结束: * text* 是不正确的,
- 必须由空格从周围的文本中分离出来。可以通过使用转义的空格来规避这个限制:thisisoneword。
docutils以后的版本可能会取消上列出的这些限制。
reST也允许自定义“文本解释role”,这就意味着所包含的文本应以一种特定的方式解释。Sphinx用它提供了语义标记和交叉引用的标识符。一般的语法格式是 :rolename:`content` 。
标准的reST提供了如下些roles:
- emphasis – 来替代 *emphasis*
- strong – 代替 **strong**
- literal – 代替 ``literal``
- subscript – 下标文本
- superscript – 上标文本
- title-reference – 书,期刊,以及其他材料的标题
Sphinx添加的roles请见 Inline markup。
列表和“类”引用块
列表标记(ref) 是自然的:只要在段落开头放置一个星号和缩进正常。带编号的列表同样适用;它们也可以自动编号通过使用标志 #:
* This is a bulleted list. * It has two items, the seconditem uses two lines.1. This is a numbered list. 2. It has two items too.#. This is a numbered list. #. It has two items too.
嵌套列表是可能的,但要知道,它们必须由空行从父列表中分隔:
* this is * a list* with a nested list* and some subitems* and here the parent list continues
定义列表 (ref) 的创建:
term (up to a line of text)Definition of the term, which must be indentedand can even consist of multiple paragraphsnext termDescription.
请注意,term 不能有一个以上的文本行。
引用段落(ref) 可以通过比周围的段落更缩进来创建。
行块元素 (ref) 是防止行被破坏的方式(保留行原样的方式):
| These lines are | broken exactly like in | the source file.
还有其它几个特殊的功能块:
- field lists (ref)
- option lists (ref)
- quoted literal blocks (ref)
- doctest blocks (ref)
源代码
文字代码块(ref)是在段尾加入特殊标记 :: 引入的。文字代码块必须缩进(像所有的段落,是通过空行来分离的):
This is a normal text paragraph. The next paragraph is a code sample::It is not processed in any way, exceptthat the indentation is removed.It can span multiple lines.This is a normal text paragraph again.
:: 标记的处理非常聪明:
- 如果出现在段落本身中,那么整个段落将会从文档中删除(也就是说不会出现在生成的文档中)。
- 如果它前面的空白,标记将被删除。
- 如果它的前面非空白,标记会被单个冒号取代。
通过这种方式,上面第二句将呈现为 “The next paragraph is a code sample:”。
表格
Sphinx支持两种表格形式。对于 格子表格 (ref),必须自己“画”自己的单元格。它们看起来像这样:
+------------------------+------------+----------+----------+ | 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 | ... | ... | | +------------------------+------------+----------+----------+
简单表格 (ref) 更容易书写,但是有限制:表格必须是两行以及以上,而且第一列不能包含多行。它们看起来像这样:
===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== =======
超链接
外部链接
使用 `Link text <http://example.com/>`_ 来实现内嵌的网页链接。如果链接文本是Web地址,你一点都不需要特殊标记,解析器可以识别在普通的文本的链接和邮件地址。
你也可以把链接和目标定义(ref)分开,像这样:
This is a paragraph that contains `a link`_... _a link: http://example.com/
内部链接
内部链接是通过Sphinx提供的一个特殊的reST role来实现的,请看 Cross-referencing arbitrary locations.
章节
章节头 (ref) 是用特殊的标点符作为章节标题的下划线来创建的(上划线是可选的),只要文字:
================= This is a heading =================
通常,没有特定的字符指定给标题级别,因为结构是用从继承的标题来确定的。对于python文档,本公约您可以按照:
- # with overline, for parts
- * with overline, for chapters
- =, for sections
- -, for subsections
- ^, for subsubsections
- ", for paragraphs
当然,您可以自由使用自己的标记字符(参看reST文档),并使用一个更深层次的嵌套级别,但请记住,大多数的目标格式(HTML,LaTeX)有限地支持嵌套深度。
显式标记
“显式标记” (ref) 在reST中是用于需要进行特殊处理的结构,比如脚注,特别突出的段落,注释,和通用指令(标识符)。
显式标记块的第一行是以 .. 开始,接着是紧随着空格,被结束于同样层级缩进的下一段落。(显式标记和正常的段落之间需要有一个空行。当你写它的时候,可能听起来有点复杂,但它是直观的。)
指令(标识符)
指令或者标识符(ref)是一个通用的显式标记块。除了roles,指令或者标识符是reST的扩展机制,Sphinx大量地使用了它。
Docutils支持如下的指令(标识符):
- 警告: attention, caution, danger, error, hint, important, note, tip, warning 以及 admonition。
- 图片:
- image (请见下面的 Images_ )
- figure (带有标题和可选的图例的图片)
- 其它内容元素:
- contents (一个局部的,即只对当前文件的,内容表)
- container (具有特定类的容器,用于HTML生成 <div> )
- rubric (一个与文件章节无关的标题)
- topic, sidebar (特别强调了内容元素)
- parsed-literal (支持行内标记的文字块)
- epigraph (带有属性行的块引用)
- highlights, pull-quote (带自己的类属性的块引用)
- compound (组合段落)
- 特色表格:
- table (带标题的表格)
- csv-table (由逗号分开的值生成的表格)
- list-table (由一系列列表生成的表格)
- 特色指令(标识符):
- raw (包括原生格式标记)
- include (包含其他文件的reStructuredText) – 在Sphinx中,当给定一个绝对的文件路径,该指令(标识符)将其作为相对于源目录来处理
- class (class属性赋给下一个元素) [1]
- HTML特性:
- meta (生成HTML <meta> 标签)
- title (覆盖文件的标题)
- Influencing markup:
- default-role (设置一个新的默认role)
- role (创建一个新的role)
请 不要 使用指令(标识符) sectnum, header 以及 footer。
Sphinx自己增加的指令(标识符)是在 Sphinx标记结构 中描述的。
基本上,指令(标识符)由一个名称,参数,选项和内容组成。(请记住这些术语,它被用来在接下来的章节描述了自定义指令或者标识符。)请看例子,:
.. function:: foo(x)foo(y, z):module: some.module.nameReturn a line of text input from the user.
function 是指令(标识符)的名称。在这里它有两个参数,第一行其余的部分以及第二行,还有一个选项 module (正如可以看到的,选项是在参数的下一行以及以冒号开始以冒号结束)。选项必须跟指令的内容缩进到相同的水平。
指令(标识符)的内容与选项之间空一行,需要相对于指令(标识符)的首行缩进(以指令的首行为缩进的对照点)。
图片
reST支持图片指令(标识符)(ref),像这样使用:
.. image:: gnu.png(options)
在Sphinx中使用图片指令(标识符),文件名(这里是指 gnu.png)必须是相对于源文件,或者是绝对的但是相对于顶部的源目录。例如,在 sketch/spam.rst 文件中可以使用图片 images/spam.png,也可以使用 ../images/spam.png 或者 /images/spam.png。
Sphinx将会自动将图像文件拷贝到输出目录中(例如HTML格式输出,会拷贝到 _static 目录中。)
对于图片尺寸选项( width 和 height)的解释如下:如果大小没有单位或单位是像素,那图片大小将会被那些支持像素的输出格式关心(LaTeX格式就不在乎这种情况的图片大小)。HTML和LaTeX输出格式使用其他的单位(像 pt 表示像素点)。
Sphinx扩展了标准的docutils的功能,允许文件扩展名为星号:
.. image:: gnu.*
Sphinx搜索所有的图片匹配提供的模式,并确定其类型。每个生成器会从所有的候选者中选择最佳的图片。比如,如果给出 gnu.* 这样的文件名以及源代码树中存在 gnu.pdf 和 gnu.png 这两个文件,LaTeX 生成器会选择前者,HTML生成器则会选择后者。
Changed in version 0.4: 增加了支持以星号结尾的文件名。
Changed in version 0.6: 图片的路径可以是绝对的。
脚注
可以使用 [#name]_ 标注在脚注的位置,在文档的最后的 .. rubric:: Footnotes 后添加脚注的内容,像这样:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_.. rubric:: Footnotes.. [#f1] Text of the first footnote. .. [#f2] Text of the second footnote.
你也可以明确用数字标注脚注或者通过不指定 name 使用自动数字标记脚注([#]_)。
引文
Sphinx支持标准reST引文(ref),增加了所有引文是“全局的”的特性,即:所有的文件可以使用所有的引文。这样使用它们:
Lorem ipsum [Ref]_ dolor sit amet... [Ref] Book or article reference, URL or whatever.
引文用法是类似的脚注的用法,但带标签不是数字,或以``#``开始。
替换
reST支持“替换”(ref),这是文本和/或标记在文中 |name| 提到。它们是像脚注用显著的标记块,像这样:
.. |name| replace:: replacement *text*
或者,这样:
.. |caution| image:: warning.png:alt: Warning!
细节请看 reST reference for substitutions。
如果你想在所有文件使用中一些替换,把它们写入 rst_prolog 或把它们放到一个单独的文件,要使用它们的所有文件中包含它,通过使用 include 指令或者标识符。(务必使得include文件扩展名与其他的源文件不同,以免让Sphinx把它作为一个独立的文件。)
Sphinx自定义了一些默认的替换, 请看 Substitutions。
评论
不是一个有效的标记结构(如上述的脚注)的每一个明确的标记块被视为一条评论(ref)。例如:
.. This is a comment.
您可以缩进文本在注释开始后,这样可以形成多行注释:
..This whole indented blockis a comment.Still in the comment.
源文件编码
由于包括特殊字符如在reST中的破折号或版权标志,最简单的方法是直接写为Unicode字符,指定编码。Sphinx假定源文件默认情况下是使用UTF-8编码;你可以改变 source_encoding 这一配置值。
陷阱
这有些问题通常发生在编写reST文档的时候:
- 分离的内嵌标记: 正如上面所说,行内标记的跨度必须用由非单词字符把周围的文字分开,可以使用转义的空格来避免。详情请看 the reference。
- 没有嵌套内联标记: 像 *see :func:`foo`* 是不可能存在的。
reStructuredText 初学者语法汇总相关推荐
- Python的基本语法汇总
Python的基本语法汇总 1.常用列表的操作 2.常用字典的操作 3.文件基本操作 4.if/else三元表达符 5.生成器表达式(不占内存) 6.Python的while语句或者for语句可以带e ...
- 【ChatGPT】输出MySQL常用语法汇总
以下是MySQL常用的语法汇总: 创建数据库 CREATE DATABASE database_name; 删除数据库 DROP DATABASE database_name; 创建表 CREATE ...
- 《最值得收藏的python3语法汇总》之运算符
目录 关于这个系列 1.算术运算符 2.比较(关系)运算符 3.赋值运算符 4.逻辑运算符 5.位运算符 6.成员运算符 7.身份运算符 ...
- Markdown 语法汇总
Markdown语法汇总 前言 我们在平时写作的时候,可能你会倾向于使用 Markdown 这种富文本标记语言,因为它是纯文本格式,而且可以很方便的生成具有很强可读性的 html 文件.比如现在很多写 ...
- 日语助词か的语法汇总,请牢记
以下是日语助词"か"的语法汇总,包括了它的多种用法和语法点: 疑问句 "か"最基本的用法就是在句末表示疑问,用于询问对方是否同意.知道或能够回答问题.例如:&q ...
- python编程语法大全-python语法汇总
广告关闭 2017年12月,云+社区对外发布,从最开始的技术博客到现在拥有多个社区产品.未来,我们一起乘风破浪,创造无限可能. splitstriplen()for variable in range ...
- reStructuredText(.rst)语法规则快速入门
原文:http://blog.useasp.net/archive/2014/09/05/rst-file-restructuredtext-markup-syntax-quikstart.aspx? ...
- 最新总结:2021那些小众精巧的 Python 语法汇总
2020 年 python2 停止维护,公司代码规范也鼓励使用 python3.6+版本,而随着 Python 版本的不断更新,许多旧的语法在可读性与效率上都已经有更好的替代了.当然,大部分的重要特性 ...
- ILOG CPLEX 部分语法汇总
从两天前开始接触CPLEX的OPL语言,各种错误不断,但网上参考资料又很少.本博文基于自己的摸索,汇总部分基础语法,以备不时之需.以TSP为例. 关键词 range 表示一个范围,使用范例:range ...
最新文章
- Java基础教程,第三讲,运算符 变量定义 数据类型转换
- Matlab中plot基本用法
- mysql按章_mysql按时间范围分区
- Android开发--TableLayout的应用
- wxWidgets:wxListView类用法
- MySQL a库备份恢复为B库_MySQL数据库备份的基础知识_MySQL
- c语言中调试时go的作用,C语言调用GO
- css设置按钮竖直方向居中_如何借助伪元素实现垂直居中?
- 第二阶段团队冲刺第九天
- tensor转换为图片_pytorch 实现张量tensor,图片,CPU,GPU,数组等的转换
- Windows Mobile如何得到资源文件中的文件
- java vector编程_java中Vector实现方法和功能还有例子详细讲解一下!谢谢!
- 假如时光倒流,我会这么学习Java 【转载】
- 为何最近我们日子会很难过 之 第一篇
- MotoSim EG-VRC软件:安川机器人仿真项目基础操作
- shopex php5.3,shopex.4.85支持php5.3 | 学步园
- Android解决监听AppBarLayout的滑动状态来动态设置标题时报requestLayout() improperly called by错误问题
- 麻雀如何变凤凰 by 网络雄猫
- 看完这篇文章你就可以告诉领导你精通Zookeeper了
- 东南大学计算机学院健在院士,【缅怀】顾冠群院士逝去,计算机界痛失泰斗
热门文章
- stm32 软件怎么设置写保护_STM32 , 写保护问题! (amobbs.com 阿莫电子论坛)
- SqlServer2016下载安装步骤详解
- 三鹿奶粉中的三聚氰胺是什么?三聚氰胺的用途与毒性
- html屏幕有闪动,笔记本电脑屏幕出现条纹闪烁怎么解决【解决方法】
- 电脑连接手机热点,无法上网
- 大数据 Hadoop 生态体系介绍
- 静态方法与非静态方法的相互调用
- 用C/CCC++实现输出双声道(立体声).wav 文件
- PMP学习笔记之一 准备篇
- 剑池CDK快速使用指南