ReStructuredText
2016年5月25日,8年前(2016-05-25)
reStructuredText(RST、ReST或reST)是一种用于文本数据的文件格式,主要用于 Python 编程语言社区的技术文档。
它是Python Doc-SIG(Documentation Special Interest Group)的 Docutils 项目的一部分,旨在为 Python 创建一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation(pod)的工具。Docutils 可以从 Python 程序中提取注释和信息,并将它们格式化为各种形式的程序文档。[1]
从这个意义上说,reStructuredText 是一种轻量级标记语言,其设计目的是令文档处理软件(如Docutils)可以处理它,和使读、写 Python 源代码的程序员很容易读它。
历史
早期的轻量级标记语言 StructuredText(由 Zope 开发)存在许多问题,reST 就是为了解决这些问题而开发的。[2]选择了 reStructuredText 这个名称是为了表明 reST 是一个“经过修改、重写和重新解释的结构化文本”。[3]
reST 在 2002 年开始在 Python 社区中得到了重要的应用。
参考实现
reST 解析器的引用实现是 Python 编程语言中的 Docutils 文本处理框架的一个组件,但是还可以使用其他解析器。
没有正式的 MIME 类型注册为 reStructuredText,但非官方的是``text/x-rst``。[4]
应用程序
reStructuredText 通常用于技术文档,例如 Python 库的文档。[5]然而,它也适用于广泛的文本。
自 2008 年以来,reST 一直是 Python 的 Sphinx 文档生成系统的核心组件。
Trac 也支持 reStructuredText,GitHub 和 Bitbucket 也是如此。[6]
为古登堡计划准备文本的分布式校对器正在考虑采用 reST 作为一种基本格式,其他电子书格式可以从这种格式生成。[7]
2016 年 7 月,Linux 内核项目决定从基于 DocBook 的文档过渡到 reStructuredText 和 Sphinx 工具链。[8]
在 3.0 版本中,软件构建工具 CMake 从自定义标记语言转换为 reStructuredText。[9]
reST标记示例
标题
节标题 ============== 小节标题 ------------------
列表
- 列表条目 - 另一个列表条目 - 子列表条目 - 列表之间空行以分隔条目 * 改变条目标点以分割列表 - 又一个条目 1) 编号列表条目 2) 另一条 a) 一个很长很长的列表条目,这条的内容太长了以至于\ 要换行书写。注意换行时左侧要对齐文本,而不是编\ 号。行末加反斜杠可避免在中文之间空格。 i) 列表里面甚至还可以 分段。 3) 第三条 #) 又一个条目 #) 再一个条目
图片
.. image:: /path/to/image.jpg
指定链接
链接到\ `维基百科`_\ 和\ `Linux 内核存档`_\ 。汉字与格式标志之间插入反斜杠和空格以进行分隔。 .. _维基百科: https://www.wikipedia.org/ .. _Linux 内核存档: https://www.kernel.org/
匿名链接
这句话可以\ `匿名链接到 Python 网站`__。
__ https://www.python.org/
N.B.: 指定链接和匿名链接用重字符(`)括起来,而不是用引号(')括起来。
文字块
:: Literal 文本 在段落最后也可以插入 Literal 文本标志符:: 又一段 Literal 文本 .. code:: python print("一段明示为 Python 语言代码的 Literal 文本")
另请参阅
- 文档标记语言比较
- 文档生成器比较(英语:Comparison of documentation generators)
- 笔记软件比较(英语:Comparison of notetaking software)
参考文献
- ^ Mertz, David. XML Matters: reStructuredText. IBM developerWorks. 2003-02-01 [2016-10-05]. (原始内容存档于2016-10-06).
- ^ Goodger, David. reStructuredText: Markup Syntax and Parser Component of Docutils. Docutils Project. 2016-05-24 [2016-10-05]. (原始内容存档于2016-10-05).
- ^ Goodger, David. Docutils FAQ (Frequently Asked Questions). Docutils Project. 2016-02-26 [2016-10-05]. (原始内容存档于2016-09-30).
- ^ What's the official MIME type for reStructuredText data? in Docutils FAQ.. Docutils Project. [2017-12-20]. (原始内容存档于2017-12-10).
- ^ Goodger, David. PEP 287 -- reStructuredText Docstring Format. Python Software Foundation. 2002-04-02 [2016-10-05]. (原始内容存档于2016-10-06).
- ^ reStructuredText Support in Trac. Trac. 2016-09-13 [2016-10-05]. (原始内容存档于2016-10-06).
- ^ Newby, Greg. Minutes of 2010 December 11 meeting. Distributed Proofreaders. 2011-01-08 [2011-01-08].
- ^ Kernel documentation with Sphinx, part 1: how we got here. LWN.net. 2016-07-06 [2016-10-27]. (原始内容存档于2016-10-25).
- ^ CMake 3.0.0 Release Notes. Kitware, Inc. 2014-06-10 [2016-10-05]. (原始内容存档于2016-12-02).
外部链接
- reStructuredText官方网站,附有参考页面(页面存档备份,存于互联网档案馆)
- 查
- 论
- 编
- Amigaguide
- CML
- C-HTML
- ConTeXt(英语:ConTeXt)
- Crossmark(英语:Crossmark)
- DITA(英语:Darwin Information Typing Architecture)
- DocBook
- eLML(英语:eLML)
- EAD(英语:Encoded Archival Description)
- Enriched text(英语:Enriched text)
- FHTML(英语:FHTML)
- GML(英语:List of document markup languages#GML Disambiguation)
- GuideML(英语:GuideML)
- HDML(英语:Handheld Device Markup Language)
- HyTime
- HyperTeX(英语:HyperTeX)
- IPF(英语:Information Presentation Facility)
- LilyPond
- LinuxDoc(英语:LinuxDoc)
- Lout(英语:Lout (software))
- MIF(英语:Maker Interchange Format)
- MAML(英语:Microsoft Assistance Markup Language)
- MEI(英语:Music Encoding Initiative)
- MusicXML
- OMDoc(英语:OMDoc)
- OpenMath(英语:OpenMath)
- POD(英语:Plain Old Documentation)
- RTML(英语:Remote Telescope Markup Language)
- RTML(英语:RTML)
- RFT(英语:Revisable-Form Text)
- S1000D(英语:S1000D)
- TEI
- Texinfo(英语:Texinfo)
- Troff
- Wikitext
- WML
- WapTV(英语:WapTV)
- XAML
- YAML