使用sphinx为你的python项目生成文档

sphinx，大家都在用的文档生成工具。

参考文献

使用sphinx快速为你python注释生成API文档

sphinx注释风格

class 注释

1
2
3
class Demo1():
    """类的功能说明"""
    pass

method 注释

无参数情况

1
2
3
def add(self,a,b):
    """两个数字相加，并返回结果"""
    return a+b

带参数的 method 注释，示例1。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
def google_style(arg1, arg2):
    """函数功能(简述)。

    函数功能说明（详细说明）。
    
    Args:
        arg1 (int): arg1的参数说明
        arg2 (str): arg2的参数说明

    Returns:
        bool: 返回值说明

    """
    
    return True

带参数的 method 注释，示例2。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
def numpy_style(arg1, arg2):
    """函数功能(简述)。

    函数功能说明（详细说明）。

    Parameters
    ----------
    arg1 : int
        arg1的参数说明
    arg2 : str
        arg2的参数说明

    Returns
    -------
    bool
        返回值说明

    """
    return True

在注释中添加代码说明的 method 注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
def my_function(a, b):
    """函数功能(简述)。

    函数功能说明（详细说明）。

     >>> my_function(2, 3)
     6
     >>> my_function('a', 3)
     'aaa'

    """
    
    return a * b

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！