使用 docstrings 編寫文件

一個文件字串是一個多行註釋用於記錄模組，類，函式和方法。它必須是它描述的元件的第一個宣告。

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

docstring 的值可以在程式中訪問， 並且 - 例如 - 由 help 命令使用。

語法約定

PEP 257

PEP 257 定義了文件字串註釋的語法標準。它基本上允許兩種型別：

• 單行 Docstrings：

根據 PEP 257，它們應該用於簡短的功能。一切都放在一行，例如：

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

文件字串應以句號結尾，動詞應以命令形式結束。

• 多行文件字串：

多行文件字串應該用於更長，更復雜的函式，模組或類。

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

它們以簡短的摘要（相當於單行文件字串的內容）開頭，它可以與引號位於同一行或下一行，提供其他詳細資訊和列表引數以及返回值。

注意 PEP 257 定義了應該在 docstring 中給出的資訊 ，它沒有定義應該給出的格式。這就是其他方和文件解析工具為文件指定自己的標準的原因，其中一些列在下面和這個問題中 。

獅身人面像

Sphinx 是一個基於 docstrings 為 Python 專案生成基於 HTML 的文件的工具。它使用的標記語言是 reStructuredText 。他們定義了自己的文件標準，pythonhosted.org 主持了對它們的非常好的描述 。例如， pycharm IDE使用 Sphinx 格式。

使用 Sphinx / reStructuredText 格式可以像這樣記錄一個函式：

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Google Python 樣式指南

Google 釋出了 Google Python 樣式指南 ，該指南定義了 Python 的編碼約定，包括文件註釋。與 Sphinx / reST 相比，許多人說根據 Google 指南的文件更易於人類閱讀。

上面提到的 pythonhosted.org 頁面還提供了一些根據 Google Style Guide 提供的良好文件示例。

使用 Napoleon 外掛，Sphinx 還可以解析符合 Google Style Guide 標準的文件。

使用 Google 樣式指南格式可以將此功能記錄為：

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4