如何为 Python 函数编写文档？

---

文档是编写代码的重要方面，尤其是在涉及函数时。它帮助其他人理解函数的作用、如何使用它以及它接收哪些参数。Python 有一个内置的文档工具，称为文档字符串。文档字符串是在函数中作为第一个语句出现的字符串，并提供有关该函数的文档。

有关函数或文档的信息放在函数中的文档字符串中。以下是编写文档字符串时应遵循的准则。

第一行应始终是对对象目的的简短、简洁的总结。为简洁起见，它不应明确说明对象的名称或类型。此行应以大写字母开头，以句号结尾。

如果文档字符串中还有更多行，则第二行应为空白，在视觉上将摘要与其余描述分开。

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 一起提供。它根据文档字符串生成文档，可以从命令行运行或用作模块。

以下是用 Sphinx 文档生成器从 `add_numbers` 函数的文档字符串生成的示例

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 模块中定义了上述函数后，您可以使用 Sphinx 为其生成文档，方法是在 .rst 文件中添加以下 reStructuredText 标记。:members: 选项告诉 Sphinx 为模块中的所有函数和类生成文档。

.. autofunction:: add_numbers
    :members:

将上述标记添加到 .rst 文件后，您可以使用 sphinx-build 命令生成文档。

sphinx-build -b html source_dir build_dir 

这将为您的 Python 模块生成 HTML 文档，包括 add_numbers 函数。生成的文档将包含函数签名、文档字符串以及您在标记中包含的任何其他相关信息。

输出

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

这会将文档打印到终端。