跳至內容

reStructuredText

本頁使用了標題或全文手工轉換
維基百科,自由的百科全書
reStructuredText
reStructuredText logo
副檔名
.rst
網路媒體型式text/x-rst
開發者David Goodger
首次發布2002年4月2日,​22年前​(2002-04-02
最新版本
Revision 7942
2016年5月25日,​8年前​(2016-05-25
免費格式?Public domain
網站docutils.sourceforge.net/rst.html

reStructuredTextRSTReSTreST)是一種用於文本數據的文件格式,主要用於 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,GitHubBitbucket 也是如此。[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 文本")

另請參閱

[編輯]

參考文獻

[編輯]
  1. ^ Mertz, David. XML Matters: reStructuredText. IBM developerWorks. 2003-02-01 [2016-10-05]. (原始內容存檔於2016-10-06). 
  2. ^ Goodger, David. reStructuredText: Markup Syntax and Parser Component of Docutils. Docutils Project. 2016-05-24 [2016-10-05]. (原始內容存檔於2016-10-05). 
  3. ^ Goodger, David. Docutils FAQ (Frequently Asked Questions). Docutils Project. 2016-02-26 [2016-10-05]. (原始內容存檔於2016-09-30). 
  4. ^ What's the official MIME type for reStructuredText data? in Docutils FAQ.. Docutils Project. [2017-12-20]. (原始內容存檔於2017-12-10). 
  5. ^ Goodger, David. PEP 287 -- reStructuredText Docstring Format. Python Software Foundation. 2002-04-02 [2016-10-05]. (原始內容存檔於2016-10-06). 
  6. ^ reStructuredText Support in Trac. Trac. 2016-09-13 [2016-10-05]. (原始內容存檔於2016-10-06). 
  7. ^ Newby, Greg. Minutes of 2010 December 11 meeting. Distributed Proofreaders. 2011-01-08 [2011-01-08]. 
  8. ^ Kernel documentation with Sphinx, part 1: how we got here. LWN.net. 2016-07-06 [2016-10-27]. (原始內容存檔於2016-10-25). 
  9. ^ CMake 3.0.0 Release Notes. Kitware, Inc. 2014-06-10 [2016-10-05]. (原始內容存檔於2016-12-02). 

外部連結

[編輯]