如何为Python函数生成文档？

在编写Python代码的过程中，我们时常需要为自己编写的函数撰写文档，以方便后来者阅读和使用。Python自带了一种文档生成工具——docstring（文档字符串）。本文将详细介绍如何为Python函数生成文档。

什么是文档字符串？

在Python中，文档字符串是指函数、类、模块等对象内部的字符串常量。这些字符串常量都需要先出现在对象的第一行，也即是函数（或类、模块）前的行。

例如下面这个Python函数 add：

def add(a, b):
    """
    This function adds two numbers

    Parameters:
        a (int): The first number
        b (int): The second number

    Returns:
        int: The sum of a and b
    """
    return a + b

上面的三个双引号括起来的部分就是函数的文档字符串。文档字符串的格式通常是这样的：

"""
Description of what this object is for

:param arg1: Description of first argument
:type arg1: Type of first argument
:param arg2: Description of second argument
:type arg2: Type of second argument
:return: Description of the object returned
:rtype: Type of the object returned
"""

在docstring中，有一些常见的特殊命令可供使用：

Parameters: 用于描述函数的输入参数，语法为:param 参数名: 参数的描述
type: 用于描述参数的类型，语法为:type 参数名: 类型
Returns: 用于描述函数的返回值，语法为:return: 返回值的描述
rtype: 用于描述返回值的类型，语法为:rtype: 类型

如何生成文档？

Python中有很多工具可用于生成文档，其中比较常用的包括：

Sphinx：Sphinx是Python官方推荐的文档生成工具，功能强大，可用于为Python代码、项目、文档生成各种格式的输出文件，例如HTML，PDF，LaTeX等。
pdoc：pdoc是一款使用简单、安装便捷的文档生成工具，可以快速为Python代码生成简洁明了的文档。
Pydoc：Pydoc是一个标准库，也可以生成Python代码的文档。不过，使用Pydoc时需要在命令行中运行来生成HTML格式的文档。

对于本文而言，我们将使用Sphinx来为Python函数生成文档。首先，需安装Sphinx。你可以用下面的命令在Python虚拟环境中安装Sphinx:

pip install sphinx

安装完毕后，需要使用Sphinx进行初始化。在要生成文档的目录下，执行以下命令:

sphinx-quickstart

Sphinx将会询问一些问题来配置生成文档的选项，选择默认设置即可。执行完毕后，目录下将会生成一个名为“docs”的目录，里面包含一个名为“index.rst”的文件和一些其他的文件和目录。

接下来，我们需要在“docs”的目录下，新建一个Python的.py文件，例如下面这个文件名为my_module.py:

def my_function(arg1, arg2):
    """
    This functions does cool stuff

    :param arg1: This is the first argument
    :type arg1: int
    :param arg2: This is the second argument
    :type arg2: str
    :return: This is the description of what it returns
    :rtype: bool
    """
    return True

在文件的顶部，我们需要添加一个模块级别的docstring，例如：

"""
This is a sample module for generating documentation in Sphinx.

This module contains a function called `my_function`, which does cool stuff. You can use this
function to do all sorts of things.

Example usage:

    >>> my_function(1, 'Hello')
    True
"""

然后，我们需要将这个.py文件包含到Sphinx的文档中去。编辑“docs”的目录下的index.rst文件，在文件中添加一个所生成文档中的章节标题，例如：

My Module
=========

.. automodule:: my_module
   :members:
   :undoc-members:
   :show-inheritance:

上述的automodule指令用来告诉Sphinx将my_module模块的文档添加到文档中。:members:选项用于生成函数的文档。:undoc-members:选项用于显示未被文档化的成员，例如模块级别或类级别的变量。:show-inheritance:选项用于显示继承关系。

接下来，我们需要使用Sphinx编译生成文档。在“docs”目录下，执行以下命令：

make html

等待命令执行完毕后，docs/build/html目录下将会生成我们的文档。我们可以使用浏览器打开docs/build/html下的index.html文件，就可以看到生成的文档了。在文档中，我们可以看到我们编写的Python函数my_function，并且其docstring中的信息也已经被正确地渲染出来了。