如何为Python函数生成文档？

文档是编写代码的重要方面，尤其是在函数方面。它帮助其他人了解功能，如何使用它以及它所需要的参数。Python有一个名为docstrings的内置文档工具。docstrings是一个字符串，出现在函数的第一个语句中，并提供有关函数的文档。

函数或文档的信息通过函数中的docstrings放置。编写docstrings需要遵循以下指南。

第一行应始终是对象用途的简短、简洁摘要。为简洁起见，不应显式说明对象的名称或类型。此行应以大写字母开头并以句点结尾。

如果文档字符串中有更多行，则第二行应为空白行，以视觉上分隔摘要和其余描述。

Sphinx

Sphinx是最流行的Python文档工具。它将重新格式化的文本标记语言转换为一系列输出格式，包括HTML、LaTeX（可打印PDF版本）、手册页面和纯文本。

在运行时，Sphinx将导入您的代码，并使用Python的内省功能提取所有函数、方法和类签名。它还将提取相应的docstrings，并将其编译成结构良好、易于阅读的文档，用于项目。

阅读更多：Python 教程

示例：docstring的简单函数

在此示例中，我们定义了一个名为 greet 的函数，其中包含一个名为 name 的参数。函数中的第一个语句是一个描述函数的docstring。docstring用三个双引号括起来。

要访问函数的docstring，可以使用内置的 help() 函数。

help() 函数会显示函数的docstring。

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.

示例：详细docstring的函数

在此示例中，我们定义了一个名为 calculate_sum 的函数，其中包含一个名为 numbers 的参数。函数的docstring提供了有关函数的更详细信息，包括其所需的参数类型和返回值类型。

同样地，我们可以使用 help() 函数来访问函数的docstring：

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.

使用docstrings是提供函数文档的好方法。它使其他人更容易理解您的代码并正确使用您的功能。

记录您的代码是一种重要的实践，可以为您和可能要处理您代码的其他开发人员节省时间和精力。适当的文档可以帮助您理解以后的代码，使他人更容易使用您的代码。以下是有关如何记录Python函数的一些提示-

例子

记录Python函数的最简单方法是使用docstrings。 docstrings是一个字符串文字，出现在模块、函数、类或方法定义的第一条语句中。可以使用对象的__doc__属性访问它。以下是具有docstring的函数示例：

在此示例中，docstring提供有关函数执行的信息，它期望哪些参数以及它返回什么。您可以通过运行help(add_numbers)或add_numbers.__doc__来访问docstring。

def add_numbers(a, b):
    """
    Adds two numbers together.
    :param a: 第一个数。
    :param b: 第二个数。
    :return: a和b的和。
    """
    return a + b
print(add_numbers.__doc__)

输出

Adds two numbers together.
   :param a: 第一个数。
   :param b: 第二个数。
   :return: a和b的和。

例子：使用类型注释

类型注释也可以用于记录函数参数和返回值的期望类型。类型注释是可选的，不影响函数的行为，但它们可以提高代码的可读性并帮助防止错误。以下是一个例子：

在此示例中，类型注释指示两个参数都应为整数，并且函数应返回一个整数。您可以通过运行add_numbers.__annotations__访问类型注释。

def add_numbers(a:int, b:int) -> int:
    """
    Adds two numbers together.
    :param a: 第一个数。
    :param b: 第二个数。
    :return: a和b的和。
    """
    return a + b
print(add_numbers.__annotations__)

输出

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

例子：使用文档生成器

虽然docstrings和类型注释很有用，但编写和维护它们可能很耗费时间。文档生成器可以基于这些注释自动生成代码文档。用于Python和其他编程语言的流行文档生成器包括Sphinx和pydoc。

Sphinx是一个流行的文档生成器，用于Python和其他编程语言。它可以生成各种格式的文档，例如HTML、PDF和EPUB。Sphinx使用一种称为reStructuredText的标记语言，类似于Markdown。

Pydoc是一个自带Python的文档生成器。它基于docstrings生成文档，并可以从命令行运行或用作模块。

以下是从“add_numbers”函数的docstring生成的Sphinx文档的示例：

def add_numbers(a:int, b:int) -> int:
    """
    Adds two numbers together.
    :param a: 第一个数。
    :param b: 第二个数。
    :return: a和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模块生成HTML文档，包括add_numbers函数。生成的文档将包括函数签名、docstring以及您在标记中包含的任何其他相关信息。

输出

add_numbers(a, b)
    将两个数字相加。

    :param a: 第一个数字。
    :param b: 第二个数字。
    :type a: int
    :type b: int
    :return: a和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:
    """
    为给定的名称返回问候语.

    :param name: 要问候的名称。
    :return: 一个字符串问候语。
    """
    return f"Hello, {name}!"

在 greet 函数的docstring中，我们提供了函数的描述以及其参数。我们使用 reStructuredText标记对docstring进行格式化。

编写文档后，使用以下命令生成HTML格式的文档：

make html

生成的文档将位于 _build/html 目录中。

示例：Pydoc文档生成器

Pydoc是一个内置的Python工具，可从Python模块生成文档。它从您代码中的docstrings生成HTML文档。下面是使用Pydoc的示例：

首先，我们将编写一个Python模块，其中包含我们要记录的函数：

# mymodule.py

def greet(name):
    """
    为给定的名称返回问候语。

    :param name: 要问候的名称。
    :return: 一个字符串问候语。
    """
    return f"Hello, {name}!"

然后，我们可以使用Pydoc为我们的模块生成文档。要生成HTML文档，请在终端中运行以下命令 –

python -m pydoc -w mymodule

这将在您当前的目录中生成一个名为mymodule.html的文件。您可以在Web浏览器中打开HTML文件以查看文档。

Pydoc还可以生成其他格式的文档，例如纯文本或手册页。要生成纯文本文档，请运行以下命令：

python -m pydoc mymodule

这将在终端中打印文档。