本頁使用了標題或全文手工轉換

reStructuredText

維基百科,自由的百科全書
跳至導覽 跳至搜尋
reStructuredText
副檔名 .rst
開發者 David Goodger
初始版本 2002年4月2日,​17年前​(2002-04-02
最新版本
Revision 7942
(2016年5月25日,​3年前​(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 是一種輕量級標記式語言,其設計目的是(a)文件處理軟體(如Docutils)可以處理它,(b)讀和寫 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標記範例[編輯]

標題[編輯]

节标题
==============

小节标题
------------------

列表[編輯]

- A bullet list item
- Second item

  - A sub item

- Spacing between items creates separate lists

- Third item

1) An enumerated list item

2) Second item

   a) Sub item that goes on at length and thus needs
      to be wrapped. Note the indentation that must
      match the beginning of the text, not the 
      enumerator.

      i) List items can even include

         paragraph breaks.

3) Third item

#) Another enumerated list item

#) Second item

圖片[編輯]

.. image:: /path/to/image.jpg

指定連結[編輯]

A sentence with links to `Wikipedia`_ and the `Linux kernel archive`_.

.. _Wikipedia: https://www.wikipedia.org/
.. _Linux kernel archive: https://www.kernel.org/

匿名連結[編輯]

Another sentence with an `anonymous link to the Python website`__.

__ https://www.python.org/

N.B.: 指定連結和匿名連結用重字元(`)括起來,而不是用引號(')括起來。

文字塊[編輯]

::

  some literal text

This may also be used inline at the end of a paragraph, like so::

  some more literal text

.. code:: python

   print("A literal block directive explicitly marked as python code")

另請參閱[編輯]

參考文獻[編輯]

  1. ^ Mertz, David. XML Matters: reStructuredText. IBM developerWorks. 2003-02-01 [2016-10-05]. 
  2. ^ Goodger, David. reStructuredText: Markup Syntax and Parser Component of Docutils. Docutils Project. 2016-05-24 [2016-10-05]. 
  3. ^ Goodger, David. Docutils FAQ (Frequently Asked Questions). Docutils Project. 2016-02-26 [2016-10-05]. 
  4. ^ What's the official MIME type for reStructuredText data? in Docutils FAQ.. Docutils Project. [2017-12-20]. 
  5. ^ Goodger, David. PEP 287 -- reStructuredText Docstring Format. Python Software Foundation. 2002-04-02 [2016-10-05]. 
  6. ^ reStructuredText Support in Trac. Trac. 2016-09-13 [2016-10-05]. 
  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]. 
  9. ^ CMake 3.0.0 Release Notes. Kitware, Inc. 2014-06-10 [2016-10-05]. 

外部連結[編輯]