reStructuredText
 |
 | |
| 副檔名 |
.rst |
|---|---|
| 網路媒體型式 | text/x-rst |
| 開發者 | David Goodger |
| 首次發佈 | 2002年4月2日 |
| 最新版本 | Revision 7942 2016年5月25日 |
| 免費格式？ | Public domain |
| 網站 | docutils |
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 文本")
另請參閱
[編輯]參考文獻
[編輯]- ^ 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）.