如何为Python函数生成文档

文档是编写代码的重要方面，特别是对于函数来说。它帮助别人了解函数的作用、如何使用以及它的参数是什么。Python有一个内置的文档工具叫做docstrings。docstrings是一个出现在函数第一条语句中的字符串，它提供了关于函数的文档。

关于函数或文档的信息放在函数的docstrings中。编写docstrings时需要遵循以下准则。

第一行应该始终是关于对象目的的简短、简洁的摘要。出于简洁考虑，它不应该明确指出对象的名称或类型。该行应以大写字母开始，以句号结束。

如果文档字符串中有更多行，则第二行应为空行，将摘要与其他详细说明分开。

Sphinx

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

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

示例：带有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.

示例：带有详细文档字符串的函数

在这个示例中，我们定义了一个名为

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.

使用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: 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': }

示例：使用文档生成器

尽管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: 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模块生成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还可以生成其他格式的文档，例如纯文本或man页。要生成纯文本文档，请运行以下命令：

python -m pydoc mymodule

这将在终端打印文档。