PEP 287 – reStructuredText Docstring 格式

作者:: David Goodger <goodger at python.org>
討論至:: Doc-SIG 郵件列表
狀態:: 活躍
型別:: 資訊性
建立日期:: 2002年3月25日
釋出歷史:: 2002年4月2日
取代:: 216

摘要
好處
目標
基本原理
規範
Docstring-重要功能
問答
版權
致謝

摘要

當純文字不足以表達內聯文件時，Python 程式設計師一直在尋找一種用於 docstring 的格式。本 PEP 提議採用 reStructuredText 標記作為 Python docstring 以及 PEP 和輔助文件中結構化純文字文件的標準標記格式。reStructuredText 是一種豐富、可擴充套件且易於閱讀的所見即所得的純文字標記語法。

本文只討論 docstring 的低階語法。本 PEP 完全不關心 docstring 的語義或處理（請參閱 PEP 256 以瞭解“Docstring PEPs 的路線圖”）。它也不是試圖廢棄純文字 docstring，純文字 docstring 始終是合法的。reStructuredText 標記是那些想要更具表達力的 docstring 的人的替代方案。

好處

程式設計師天生就是懶惰的。我們透過函式、類、模組和子系統重用程式碼。透過其 docstring 語法，Python 允許我們從內部文件化我們的程式碼。Python 文件特別興趣小組 (Doc-SIG) 的“聖盃”是一種標記語法和工具集，可以實現自動文件，其中 Python 系統的 docstring 可以根據上下文提取並處理成有用的、高質量的文件，用於多種目的。

文件標記語言有三類客戶：編寫文件的作者、處理資料的軟體系統以及最終消費者（最重要的群體）——讀者。大多數標記都是為作者和軟體系統設計的；讀者只能看到處理後的形式，無論是在紙上還是透過瀏覽器軟體。reStructuredText 則不同：它旨在以原始碼形式易於閱讀，無需預先了解標記。reStructuredText 以純文字格式完全可讀，並且許多標記形式與常見用法匹配（例如，*強調*），因此閱讀起來非常自然。然而，它足夠豐富以生成複雜的文件，並且可擴充套件，因此限制很少。當然，要編寫 reStructuredText 文件需要一些預先知識。

該標記提供了功能性和表達性，同時在源文字中保持了易讀性。處理後的形式（HTML 等）使讀者可以訪問所有內容：內聯即時超連結；與腳註之間的即時連結；自動目錄（帶即時連結！）；表格；用於圖表等的影像；令人愉悅、易讀的樣式文字。

reStructuredText 解析器現已可用，是 Docutils 專案的一部分。獨立的 reStructuredText 文件和 PEP 可以轉換為 HTML；其他輸出格式的寫入器正在開發中，並將隨著時間的推移而可用。一個 Python 源“閱讀器”的工作正在進行中，它將實現從 docstring 的自動文件。鼓勵現有自動文件工具的作者將 reStructuredText 解析器整合到他們的專案中，或者更好的是，聯手為 Python 標準庫生產一套世界級的工具。

工具將在不久的將來可用，它們將允許程式設計師從現有的 docstring 中“免費”生成用於線上幫助的 HTML、用於多種用途的 XML，以及最終用於列印文件的 PDF、DocBook 和 LaTeX。採用標準至少將透過防止進一步“重複發明輪子”來惠及 docstring 處理工具。

最終，PyDoc（現有的唯一標準自動文件工具）可以新增 reStructuredText 支援。在此期間，它對 reStructuredText 標記不會有任何問題，因為它將所有 docstring 視為預格式化的純文字。

目標

這些是 Doc-SIG 中討論的 docstring 格式的普遍接受的目標

它必須以原始碼形式對普通觀察者可讀。
它必須易於使用任何標準文字編輯器輸入。
它不需要包含可以從解析模組中推匯出的資訊。
它必須包含足夠的資訊（結構），以便可以轉換為任何合理的標記格式。
必須能夠在 docstring 中編寫模組的整個文件，而不會感到受標記語言的限制。

reStructuredText 達到了並超越了所有這些目標，並設定了自己更嚴格的目標。請參閱下面的 Docstring-重要功能。

本 PEP 的目標如下

將 reStructuredText 確立為 docstring（Python 模組和包的內聯文件）、PEPs、README 型別檔案和其他獨立文件的標準結構化純文字格式。將透過 Python 社群共識和最終的 BDFL 宣告尋求“接受”狀態。
請注意，reStructuredText 被提議為一個標準，而不是 唯一的 標準。它的使用將完全是可選的。那些不想使用它的人不必使用。
徵求並解決 Python 社群提出的任何相關問題。
鼓勵社群支援。只要存在多個相互競爭的標記，開發社群就會分裂。一旦標準存在，人們就會開始使用它，並且勢頭將不可避免地聚集起來。
整合來自相關自動文件專案的努力。希望感興趣的開發人員能夠聯手開發一個聯合/合併/通用實現。

一旦 reStructuredText 成為 Python 標準，就可以將精力集中在工具上，而不是爭論標準。Python 需要一套標準的文件工具。

關於 PEPs，可以採用以下一種或兩種策略

保持現有 PEP 部分結構構造（單行部分標題，縮排正文）。子部分可以被禁止，或者透過縮排正文中的 reStructuredText 樣式下劃線標題來支援。
用 reStructuredText 語法替換 PEP 部分結構構造。部分標題將需要下劃線，子部分將開箱即用，並且正文無需縮排（除了塊引用）。

推薦策略 (b)，並且其實現已完成。

對 RFC 2822 標題的支援已新增到 PEP 的 reStructuredText 解析器中（在特定上下文：文件的第一個連續塊中是明確的）。可能需要具體指定 PEP 部分標題允許哪些上/下劃線樣式，以保持一致性。

基本原理

docstring 缺乏標準語法阻礙了用於將 docstring 提取和轉換為標準格式（例如 HTML、DocBook、TeX）文件的標準工具的開發。已經有許多提議的標記格式和變體，以及許多與這些提議相關的工具，但如果沒有標準的 docstring 格式，它們未能獲得強大的追隨者，和/或半途而廢。

在 Doc-SIG 存在的整個過程中，從未就單一標準 docstring 格式達成共識。出於以下原因（以及其他原因），人們一直在尋求一種輕量級、隱式的標記

在 Python 程式碼中編寫的 docstring 可以從互動式直譯器中獲取，並且可以“列印”。因此，使用純文字易於閱讀。
程式設計師希望為他們的 docstring 新增結構，而又不犧牲原始 docstring 的可讀性。未修飾的純文字無法轉換為（“升級”）有用的結構化格式。
顯式標記（如 XML 或 TeX）被普遍認為是外行人難以閱讀的。
隱式標記在美學上與簡潔的 Python 語法相容。

多年來，在 Doc-SIG 上提出了許多用於 docstring 的替代標記；下面列出了一個有代表性的樣本。每個樣本都根據上述目標進行了簡要分析。請注意，這並非旨在成為所有現有標記系統的獨佔列表；還有許多其他標記（Texinfo、Doxygen、TIM、YODL、AFT 等）未提及。

XML、SGML、DocBook、HTML、XHTML
XML 和 SGML 是顯式、格式良好的元語言，適用於各種文件。XML 是 SGML 的一個變體。它們最好用於幕後，因為對於未經訓練的眼睛來說，它們冗長、難以輸入，並且作為原始碼閱讀時過於混亂。DocBook、HTML 和 XHTML 都是 SGML 和/或 XML 的應用程式，並且都共享相同的基本語法和相同的缺點。
TeX
TeX 與 XML/SGML 類似，因為它也是顯式的，但它不太容易編寫，對於未經訓練的人來說也不容易閱讀。
Perl POD
大多數 Perl 模組都以一種稱為 POD（Plain Old Documentation）的格式進行文件化。這是一種易於輸入、非常低階的格式，與 Perl 解析器緊密整合。有許多工具可以將 POD 文件轉換為其他格式：資訊、HTML 和 man 頁面等等。然而，POD 語法在可讀性方面繼承了 Perl 本身。
JavaDoc
Java 類和函式前的特殊註釋用於文件化程式碼。一個用於提取這些註釋並將其轉換為 HTML 文件的程式稱為 javadoc，它是標準 Java 發行版的一部分。然而，JavaDoc 與 HTML 關係非常密切，使用 HTML 標籤進行大部分標記。因此，它也存在 HTML 的可讀性問題。
Setext, StructuredText
早期，Setext（結構增強文字）的變體，包括 Zope 公司的 StructuredText，被提議用於 Python docstring 格式化。此後，這些變體將統稱為“STexts”。STexts 的優點是無需特殊知識即可輕鬆閱讀，並且相對容易編寫。

儘管一些人（包括大多數現有 Python 自動文件工具）在使用，但到目前為止 STexts 未能成為標準，因為
- STexts 不完整。缺乏人們希望在其 docstring 中使用的“基本”結構，使得 STexts 不盡理想。請注意，這些“基本”結構並非普遍存在；每個人都有自己的要求。
- STexts 有時令人驚訝。文字的某些部分被意外地解釋為被標記，導致使用者沮喪。
- SText 實現存在 bug。
- 大多數 STexts 都沒有正式的規範，除了實現本身。一個有 bug 的實現意味著一個有 bug 的規範，反之亦然。
- 當標記字元用於非標記上下文時，沒有辦法繞過 SText 標記規則。換句話說，沒有辦法轉義標記。

隱式 STexts 的支持者強烈反對顯式標記（XML、HTML、TeX、POD 等）的提議，自 1996 年或更早以來，辯論時斷時續。

reStructuredText 是 SText 思想的完整修訂和重新詮釋，解決了上面列出的所有問題。

規範

reStructuredText 的規範和使用者文件非常廣泛。此處不重複或總結所有內容，而是提供原始連結。

請先閱讀 reStructuredText 入門，這是一個簡短而溫和的介紹。快速 reStructuredText 使用者參考快速總結了所有標記結構。有關完整和詳細的資訊，請參閱以下文件

此外，StructuredText 的問題解釋了許多關於 StructuredText 的標記決策，而 reStructuredText 語法替代方案記錄記錄了獨立做出的標記決策。

Docstring-重要功能

一種標記轉義機制。
反斜槓（\）用於在非標記目的需要時轉義標記字元。然而，內聯標記識別規則的構建旨在最大程度地減少對反斜槓轉義的需求。例如，儘管星號用於強調，但在“*”或“(*)”或“x * y”等非標記上下文中，星號不會被解釋為標記並保持不變。對於許多非標記用途的反斜槓（例如，描述正則表示式），內聯字面量或字面量塊是適用的；請參閱下一項。
用於包含 Python 原始碼和 Python 互動會話的標記：內聯字面量、字面量塊和 doctest 塊。
內聯字面量使用 雙反引號 來指示程式 I/O 或程式碼片段。在內聯字面量中不進行任何標記解釋（包括反斜槓轉義 [\] 解釋）。

字面量塊（塊級字面量文字，例如程式碼摘錄或 ASCII 圖形）是縮排的，並在前一個段落末尾用雙冒號（“::”）指示（就在這裡——>）
```
if literal_block:
    text = 'is left as-is'
    spaces_and_linebreaks = 'are preserved'
    markup_processing = None
```
Doctest 塊以“>>>”開頭，以空行結束。不需要縮排或字面量塊雙冒號。例如
```
Here's a doctest block:

>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive sessions)'
(cut and pasted from interactive sessions)
```

隔離 Python 識別符號的標記：解釋文字。

用單反引號括起來的文字被識別為“解釋文字”，其解釋取決於應用程式。在 Python docstring 的上下文中，解釋文字的預設解釋是 Python 識別符號。文字將用一個超連結標記，該超連結連線到給定識別符號的文件。查詢規則與 Python 本身相同：LGB 名稱空間查詢（本地、全域性、內建）。解釋文字的“角色”（識別類、模組、函式等）從名稱空間查詢中隱式確定。例如

class Keeper(Storer):

    """
    Keep data fresher longer.

    Extend `Storer`.  Class attribute `instances` keeps track
    of the number of `Keeper` objects instantiated.
    """

    instances = 0
    """How many `Keeper` objects are there?"""

    def __init__(self):
        """
        Extend `Storer.__init__()` to keep track of
        instances.  Keep count in `self.instances` and data
        in `self.data`.
        """
        Storer.__init__(self)
        self.instances += 1

        self.data = []
        """Store data in a list, most recent last."""

    def storedata(self, data):
        """
        Extend `Storer.storedata()`; append new `data` to a
        list (in `self.data`).
        """
        self.data = data

每段解釋文字都根據包含其 docstring 的塊的區域性名稱空間進行查詢。

隔離 Python 識別符號並指定其型別的標記：帶有角色的解釋文字。
儘管 Python 原始碼上下文閱讀器設計為不需要顯式角色，但它們仍然可以使用。要明確分類識別符號，角色可以以字首或字尾形式與識別符號一起給出。
```
Use :method:`Keeper.storedata` to store the object's data in
`Keeper.data`:instance_attribute:.
```
為角色選擇的語法很冗長，但這是必要的（如果有人有更好的替代方案，請將其釋出到 Doc-SIG）。該標記的目的是應該很少需要使用顯式角色；它們的使用應保持在絕對最小值。
用於“標籤列表”或“欄位列表”的標記：欄位列表。
欄位列表表示從欄位名稱到欄位主體的對映。這些主要用於擴充套件語法，例如“書目欄位列表”（表示文件元資料，如作者、日期和版本）和指令的擴充套件屬性（見下文）。它們可用於實現方法論（docstring 語義），例如識別引數、引發的異常等；此類用法超出了本 PEP 的範圍。

使用修改後的 RFC 2822 語法，在欄位名稱之前和之後都有冒號。欄位主體也更加通用；它們可以包含多個欄位主體（甚至巢狀的欄位列表）。例如
```
:Date: 2002-03-22
:Version: 1
:Authors:
    - Me
    - Myself
    - I
```
標準 RFC 2822 標頭語法不能用於此構造，因為它具有歧義性。在一行的開頭跟著冒號的單詞在書面文字中很常見。
標記可擴充套件性：指令和替換。
指令用作 reStructuredText 的擴充套件機制，一種在不新增新語法的情況下支援新塊級構造的方法。已經實現了用於影像、警告（註釋、警告等）和目錄生成（等等）的指令。例如，以下是如何放置影像
```
.. image:: mylogo.png
```
替換定義允許塊級指令的功能和靈活性由內聯文字共享。例如
```
The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png
```

節結構標記。

reStructuredText 中的節標題透過下劃線（和可能上劃線）修飾，而不是縮排。例如

This is a Section Title
=======================

This is a Subsection Title
--------------------------

This paragraph is in the subsection.

This is Another Section Title
=============================

This paragraph is in the second section.

問答

reStructuredText 足夠豐富嗎？
是的，對於大多數人來說是。如果它缺少特定應用程式所需的某些構造，可以透過指令機制新增。如果忽略了有用且常見的構造，並且找到了合適的可讀語法，則可以將其新增到規範和解析器中。
reStructuredText 是不是太豐富了？
對於特定的應用程式或個人來說，也許是。總的來說，不是。

從一開始，每當在 Doc-SIG 上提出 docstring 標記語法時，總會有人抱怨缺乏對某種構造的支援。回覆通常是，“我們談論的是 docstring，docstring 不應該有複雜的標記。”問題在於，對一個人來說似乎多餘的構造，對另一個人來說可能絕對是必不可少的。

reStructuredText 採取了相反的方法：它提供了一組豐富的隱式標記構造（加上一個用於顯式標記的通用擴充套件機制），允許各種文件。如果這組構造對於特定應用程式來說過於豐富，那麼未使用的構造可以透過應用程式特定的覆蓋從解析器中刪除，或者只是透過約定省略。
為什麼不使用縮排表示節結構，就像 StructuredText 那樣？它不是更“Pythonic”嗎？
Guido van Rossum 在 2001 年 6 月 13 日的 Doc-SIG 帖子中寫道

我仍然認為使用縮排來表示分節是錯誤的。如果你看看真實的書籍和其他印刷出版物是如何排版的，你會發現縮排經常被使用，但主要是在節內部級別。縮排可以用來偏移列表、表格、引文、示例等等。（認為 docstring 是不同的，因為它們是文字格式化程式的輸入，這種論點是錯誤的：重點是它們也可以在不經過處理的情況下閱讀。）
我反對使用縮排是 Pythonic 的論點：文字不是程式碼，存在不同的傳統和慣例。人們為了可讀性而展示文字已經超過 30 個世紀了。我們不要不必要地創新。

有關進一步闡述，請參閱 StructuredText 的問題中透過縮排進行節結構。
為什麼將 reStructuredText 用於 PEPs？現有的標準有什麼問題？
現有的 PEP 標準在一般表達方面非常有限，對於這種引用豐富的文件型別來說，引用尤其缺乏。PEPs 目前被轉換為 HTML，但結果（大多是等寬文字）缺乏吸引力，並且 HTML 的大部分增值潛力（尤其是內聯超連結）尚未被開發。

將 reStructuredText 作為 PEP 的標準標記將實現更豐富的表達，包括支援節結構、內聯標記、圖形和表格。在幾個 PEP 中有 ASCII 圖形圖表，這是純文字文件所能支援的全部。由於 PEP 以 HTML 形式提供，因此包含適當圖表的能力將立即派上用場。

當前的 PEP 實踐允許在文字中使用“[1]”形式的引用標記，並且腳註/參考文獻本身列在文件末尾的某個部分。目前，引用標記和腳註/參考文獻之間沒有超連結（這可以透過新增到 pep2html.py 中來實現，但目前的“標記”是模糊的，錯誤將不可避免）。包含許多引用（例如這個 ;-) 的 PEP 需要大量的來回翻閱。在修訂 PEP 時，通常會新增新引用或刪除未使用的引用。重新編號引用很痛苦，因為它必須在兩個地方完成，並且可能產生連鎖效應（插入一個新引用 1，所有其他引用都必須重新編號；始終將新引用新增到末尾是次優的）。引用很容易不同步。

PEPs 將引用用於兩個目的：簡單的 URL 引用和腳註。reStructuredText 區分兩者。PEP 可能包含如下引用
```
Abstract

    This PEP proposes adding frungible doodads [1] to the core.
    It extends PEP 9876 [2] via the BCA [3] mechanism.

...

References and Footnotes

    [1] http://www.example.org/

    [2] PEP 9876, Let's Hope We Never Get Here
        http://peps.python.org/pep-9876/

    [3] "Bogus Complexity Addition"
```
引用 1 是一個簡單的 URL 引用。引用 2 是包含文字和 URL 的腳註。引用 3 是僅包含文字的腳註。用 reStructuredText 重寫後，這個 PEP 可能看起來像這樣
```
Abstract
========

This PEP proposes adding `frungible doodads`_ to the core.  It
extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.

...

References & Footnotes
======================

.. _frungible doodads: http://www.example.org/

.. [#pep9876] PEP 9876, Let's Hope We Never Get Here

.. [#] "Bogus Complexity Addition"
```
如果需要，URL 和腳註可以定義在其引用附近，使其在源文字中更易閱讀，並使 PEP 更易於修訂。“參考文獻和腳註”部分可以透過文件樹轉換自動生成。整個 PEP 中的腳註將收集並顯示在標準標題下。如果 URL 引用也應明確寫出（以引文形式），則可以使用另一個樹轉換。

URL 引用可以命名（“可分解的小玩意”），並且可以在文件中的多個位置引用，而無需額外的定義。當轉換為 HTML 時，引用將替換為內聯超連結（HTML <a> 標籤）。這兩個腳註會自動編號，因此它們將始終保持同步。第一個腳註還包含一個內部引用名稱“pep9876”，因此在源文字中更容易看到引用和腳註之間的連線。命名腳註可以多次引用，保持編號一致。

“#pep9876”腳註也可以用引文的形式寫成
```
It extends PEP 9876 [PEP9876]_ ...

.. [PEP9876] PEP 9876, Let's Hope We Never Get Here
```
腳註是帶編號的，而引文則使用文字作為其引用。
將 docstring 和 PEP 提案分開會更好嗎？
如果認為不需要 PEP 標記，則可以刪除 PEP 標記提案，或者將其作為單獨的 PEP。如果獲得接受，PEP 1，《PEP 目的和指南》，以及 PEP 9，《純文字 PEP 模板示例》將進行更新。

在 Python 中，為所有結構化純文字用途採用單一一致的標記標準，並將其集中在一處提出，這似乎很自然。
現有的 pep2html.py 指令碼將現有的 PEP 格式轉換為 HTML。新格式的 PEPs 將如何轉換為 HTML？
一個集成了 reStructuredText 解析功能的新版 pep2html.py 已完成。Docutils 專案透過“PEP 閱讀器”元件支援 PEPs，包括 pep2html.py 中當前的所有功能（PEP 和 RFC 引用的自動識別、電子郵件遮蔽等）。
誰來將現有的 PEPs 轉換為 reStructuredText？
PEP 作者或志願者可以根據需要轉換現有的 PEP，但沒有這樣的要求。基於 reStructuredText 的 PEP 將與舊的 PEP 標準共存。答案 6 中提到的 pep2html.py 同時處理新舊標準。
為什麼將 reStructuredText 用於 README 和其他輔助檔案？
答案 4 中給出的關於 PEP 的理由也適用於 README 和其他輔助檔案。透過採用標準標記，這些檔案可以轉換為美觀的交叉引用 HTML，併發布到 python.org 上。其他專案的開發人員也可以利用此功能進行自己的文件。
與現有標記慣例表面上的相似性會不會造成問題，導致人們編寫無效標記（並且沒有注意到，因為純文字看起來很自然）？reStructuredText 對“不太正確”的標記的寬容度如何？
會出現一些失誤，就像從一種程式語言轉向另一種程式語言一樣。與任何語言一樣，熟練程度隨著經驗的增長而提高。幸運的是，reStructuredText 確實是一種非常小的語言。

與任何語法一樣，也存在語法錯誤的可能。期望使用者對其輸入執行處理系統並檢查輸出的正確性。

嚴格來說，reStructuredText 解析器非常嚴格（它也應該如此；“面對歧義，拒絕猜測的誘惑” 既適用於解析標記也適用於計算機語言）。以下是 reStructuredText 簡介中的設計目標 3

明確。標記規則不得開放解釋。對於任何給定的輸入，應該只有一個可能的輸出（包括錯誤輸出）。

雖然不寬容，但解析器同時也會透過生成有用的診斷輸出（“系統訊息”）來提供幫助。解析器會報告問題，並指示其嚴重程度（從低到高：除錯、資訊、警告、錯誤、嚴重）。使用者或客戶端軟體可以決定報告閾值；他們可以忽略低級別問題，或者導致高級別問題立即停止處理。問題在解析期間報告幷包含在輸出中，通常在問題源和解釋問題的系統訊息之間有雙向連結。
Python 標準庫模組中的 docstring 會轉換為 reStructuredText 嗎？
不會。Python 的庫參考文件是與原始碼分開維護的。Python 標準庫中的 docstring 不應試圖複製庫參考文件。Python 標準庫中 docstring 的當前策略是，它們應該僅僅是簡潔的提示，簡單且不帶標記（儘管許多確實包含臨時隱式標記）。
我想用 Unicode 編寫所有字串。會有什麼問題嗎？
解析器完全支援 Unicode。Docutils 支援任意輸入和輸出編碼。
社群為什麼需要一個新的結構化文字設計？
現有的結構化文字設計存在缺陷，原因如上文“理由”所述。reStructuredText 的目標是在“可讀純文字”媒介的限制內，成為一個完整的標記語法。
現有文件方法有什麼問題？
現有的方法是什麼？對於 Python docstring，目前沒有官方標準標記格式，更不用說類似於 JavaDoc 的文件方法了。方法論的問題比語法（本 PEP 旨在解決）的層次要高得多。它可能更具爭議性且更難解決，因此有意排除在本次討論之外。

版權

本文件已置於公共領域。

致謝

部分文字借用了 Moshe Zadka 編寫的 PEP 216，《Docstring 格式》。

特別感謝 Python Doc-SIG 的所有過去和現在的成員。

來源：https://github.com/python/peps/blob/main/peps/pep-0287.rst

上次修改：2025-02-01 08:59:27 GMT