如何为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

这会将文档打印到终端。