如何為Python函式編寫文件？

---

編寫程式碼時，文件編寫是一個重要方面，尤其是在涉及函式時。它可以幫助其他人理解函式的功能、使用方法以及它接受的引數。Python有一個內建的文件工具，稱為文件字串(docstrings)。文件字串是一個字串，它作為函式中的第一個語句出現，並提供有關該函式的文件。

函式的資訊或文件都放在函式的文件字串中。以下是編寫文件字串時應遵循的準則。

第一行應始終是對物件用途的簡短、簡潔的摘要。為簡潔起見，它不應明確說明物件的名稱或型別。這一行應以大寫字母開頭，以句號結尾。

如果文件字串中還有更多行，則第二行應留空，以視覺方式將摘要與其餘說明分開。

Sphinx

Sphinx是Python最流行的文件工具。它將reStructuredText標記語言轉換為一系列輸出格式，包括HTML、LaTeX（用於可列印的PDF版本）、手冊頁和純文字。

執行時，Sphinx將匯入您的程式碼，並使用Python的內省功能提取所有函式、方法和類的簽名。它還將提取附帶的文件字串，並將所有這些編譯成專案結構良好且易於閱讀的文件。

示例：帶有文件字串的簡單函式

在這個示例中，我們定義了一個名為`greet`的函式，它接受一個名為`name`的引數。函式中的第一個語句是一個文件字串，描述了函式的功能。文件字串用三個引號括起來。

要訪問函式的文件字串，可以使用內建的`help()`函式。

`help()`函式顯示函式的文件字串。

def greet(name):
    """
    This function greets the person passed in as a parameter.
    """
    print("Hello, " + name + ". How are you doing?")

# call the function
greet("John")
help(greet)

輸出

Hello, John. How are you doing?
Help on function greet in module __main__:
greet(name)
This function greets the person passed in as a parameter.

示例：帶有詳細文件字串的函式

在這個示例中，我們定義了一個名為`calculate_sum`的函式，它接受一個名為`numbers`的引數。函式的文件字串提供了有關函式的更詳細資訊，包括它接受的引數型別以及它返回的值型別。

同樣，我們可以使用`help()`函式訪問函式的文件字串。

def calculate_sum(numbers):
    """
    This function calculates the sum of a list of numbers.
    
    Parameters:
    numbers (list): A list of numbers to be summed.
    
    Returns:
    int: The sum of the list of numbers.
    """
    total = 0
    for num in numbers:
        total += num
    return total

# call the function
print(calculate_sum([1, 2, 3, 4, 5]))
help(calculate_sum)

輸出

15
Help on function calculate_sum in module __main__:
calculate_sum(numbers)
This function calculates the sum of a list of numbers.
Parameters:
numbers (list): A list of numbers to be summed.
Returns:
int: The sum of the list of numbers.

使用文件字串是為函式提供文件的好方法。它使其他人更容易理解您的程式碼並正確使用您的函式。

為程式碼編寫文件是一個重要的實踐，可以為您和其他可能處理您的程式碼的開發者節省時間和精力。正確的文件可以幫助您稍後理解自己的程式碼，並使其他人更容易使用您的程式碼。以下是一些關於如何為Python函式編寫文件的技巧：

示例

為Python函式編寫文件最簡單的方法是使用文件字串。文件字串是一個字串字面量，出現在模組、函式、類或方法定義中的第一個語句。可以使用物件的`__doc__`屬性訪問它。以下是一個帶有文件字串的函式示例

在這個示例中，文件字串提供有關函式的功能、預期引數以及返回值的資訊。您可以透過執行`help(add_numbers)`或`add_numbers.__doc__`來訪問文件字串。

def add_numbers(a, b):
    """
    Adds two numbers together.
    :param a: The first number.
    :param b: The second number.
    :return: The sum of a and b.
    """
    return a + b
print(add_numbers.__doc__)

輸出

Adds two numbers together.
   :param a: The first number.
   :param b: The second number.
   :return: The sum of a and b.

示例：使用型別註解

型別註解也可以用來記錄函式引數和返回值的預期型別。型別註解是可選的，不會影響函式的行為，但它們可以提高程式碼的可讀性，並有助於防止錯誤。這是一個例子

在這個示例中，型別註解表明兩個引數都應該是整數，並且函式應該返回一個整數。您可以透過執行`add_numbers.__annotations__`來訪問型別註解。

def add_numbers(a:int, b:int) -> int:
    """
    Adds two numbers together.
    :param a: The first number.
    :param b: The second number.
    :return: The sum of a and b.
    """
    return a + b
print(add_numbers.__annotations__)

輸出

{'a': , 'b': , 'return': }

示例：使用文件生成器

雖然文件字串和型別註解很有用，但編寫和維護它們可能很費時。文件生成器可以根據這些註解自動為您的程式碼生成文件。Python流行的文件生成器包括Sphinx和pydoc。

Sphinx是一個流行的文件生成器，用於Python和其他程式語言。它可以生成各種格式的文件，例如HTML、PDF和EPUB。Sphinx使用一種稱為reStructuredText的標記語言，它類似於Markdown。

Pydoc是一個內建的文件生成器，隨Python一起提供。它根據文件字串生成文件，可以從命令列執行或用作模組。

這是一個根據`add_numbers`函式的文件字串生成的Sphinx文件示例

def add_numbers(a:int, b:int) -> int:
    """
    Adds two numbers together.
    :param a: The first number.
    :param b: The second number.
    :return: The sum of a and b.
    """
    return a + b

在Python模組中定義了上述函式後，您可以透過將以下reStructuredText標記新增到.rst檔案中來使用Sphinx為其生成文件。`:members:`選項告訴Sphinx為模組中的所有函式和類生成文件。

.. autofunction:: add_numbers
    :members:

將上述標記新增到.rst檔案後，可以使用sphinx-build命令生成文件

sphinx-build -b html source_dir build_dir 

這將為您的Python模組（包括`add_numbers`函式）生成HTML文件。生成的文件將包含函式簽名、文件字串以及您在標記中包含的任何其他相關資訊。

輸出

add_numbers(a, b)
    Adds two numbers together.

    :param a: The first number.
    :param b: The second number.
    :type a: int
    :type b: int
    :return: The sum of a and b.
    :rtype: int

示例：Sphinx文件生成器

Sphinx是一個常用的文件生成器，用於編寫Python專案的文件。它允許您使用reStructuredText標記以純文字形式編寫文件，並從原始碼生成HTML、PDF和其他格式。以下是如何使用Sphinx編寫Python函式文件的示例

首先，您需要安裝Sphinx

!pip install sphinx

然後，為您的Sphinx文件建立一個新目錄，並使用以下命令初始化它

sphinx-quickstart

按照提示配置您的Sphinx專案。當系統提示您提供文件根目錄的路徑時，輸入包含Python程式碼的目錄的路徑。

專案設定完成後，您可以使用reStructuredText標記編寫Python函式的文件。

這是一個例子 -

def greet(name: str) -> str:
    """
    Return a greeting for the given name.
    
    :param name: The name to greet.
    :return: A string greeting.
    """
    return f"Hello, {name}!"

在`greet`函式的文件字串中，我們提供了對函式的功能及其引數的描述。我們使用reStructuredText標記來格式化文件字串。

編寫文件後，您可以使用以下命令生成HTML格式的文件

make html

生成的文件將位於`_build/html`目錄中。

示例：Pydoc文件生成器

Pydoc是用於從Python模組生成文件的內建Python工具。它根據程式碼中的文件字串生成HTML文件。以下是如何使用Pydoc的示例

首先，我們將編寫一個Python模組，其中包含我們要記錄的函式

# mymodule.py

def greet(name):
    """
    Return a greeting for the given name.
    
    :param name: The name to greet.
    :return: A string greeting.
    """
    return f"Hello, {name}!"

接下來，我們可以使用Pydoc為我們的模組生成文件。要在終端中生成HTML文件，請執行以下命令：

python -m pydoc -w mymodule

這將在當前目錄中生成一個名為`mymodule.html`的檔案。您可以在Web瀏覽器中開啟HTML檔案以檢視文件。

Pydoc還可以生成其他格式的文件，例如純文字或手冊頁。要生成純文字文件，請執行以下命令

python -m pydoc mymodule

這會將文件列印到終端。