Python基础(二十一): 注释文档 和 导出文档

一、给类添加注释文档

• 格式

class 类名:
    """
    这里是类的注释, 用来描述类的作用, 类的构造函数等等
    Attributes:
        这里写上类的属性注释
    """
    
    def 方法名(self, arg1, arg2...):
        """
        这里注释方法的作用效果
        :param arg1: 参数的含义, 参数的类型, 是否有默认值
        :param arg2: 参数的含义, 参数的类型, 是否有默认值
        :return: 返回的结果的含义, 返回值的类型
        """
        pass

• 示例:

class Person:
    """
    这是一个Person类, 用来描述人的信息
    Attributes:
        name: 人的名字, str类型, 默认值是 zhangsan
        age: 人的年龄, int类型, 默认值是 18
    """
    name = "zhangsan"
    age = 18
    
    def run(self, location):
        """
        打印调用者奔跑的位置
        :param location: 人奔跑的位置, str类型, 没有默认值
        :return: 没有返回值
        """
        print("奔跑在", location)

• 可以使用help()函数查看类的注释信息

help(Person)

• 下面是类的打印信息

二、生成项目文档

• 在项目中, 我们给类和函数添加注释之后, 可以将他们以html的方式导出来, 生成项目文档
• 生成项目文档, 就需要使用Python的内置模块pydoc

1、查看文档描述

• 使用pydoc, 需要使用到终端命令行

• python3 -m pydoc 模块名称: 查看指定模块名称的文档描述

• 比如现在工程中有一个Python.py文件, 如下图

• 我们可以在终端中输入python3 -m pydoc Python, 来查看整个模块中的文档描述

# 首先cd到Python.py文件所在文件夹(Python.py文件在桌面的Python3文件夹中)
cd /Users/binglingtian/Desktop/Python/Python3

# 接着执行命令, 查看文档描述
python3 -m pydoc Python

• 查看到的文档描述如下图

2、在网页中查看文档描述

• 上面已经可以在终端中查看文档描述, 但是这种文档是没办法给其他人看的
• 此时我们可以在浏览器中查看文档描述
• 使用命令python3 -m pydoc -p 端口号, 可以在网页中查看所有的文档描述, 其中端口号必须是没有被占用的

# 使用端口号1234
python3 -m pydoc -p 1234

• 终端内容:

➜  Python3 python3 -m pydoc -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>

• 这里有两个选项, 此时我们选择[b]rowser, 只需要在终端继续输入b即可, 然后回车

• 此时终端如下图:

• 同时浏览器自动打开一个网页, 这个网页中就是该项目所有的文档描述

• 我们可以找到Python选项, 查看文档内容(注意: Python是我给文件取的名称, 如果是其他名称的文件夹, 就需要找到对应的选项)

• 然后在终端中输入q, 就可以关闭本地服务器了, 此时刷新网页就无法再次打开

注意: python3 -m pydoc -b: 自动找到没有被占用的宽口号, 在浏览器中打开文档描述, 推荐使用

3、将项目的文档生成一个本地html文件

• 可以使用命令python3 -m pydoc -w 目标模块名, 生成一个html文件, 其中包含着该项目的文档描述

注意: 这里的目标模块名, 必须和需要生成文档的文件名称保持一致(不带扩展名)

• 终端中执行命令

# 因为模块名(文件名)是Python, 所以需要使用Python
python3 -m pydoc -w Python

• 查看生成的Python.html文件

• 使用浏览器打开Python.html文件, 可以查看网页版的文档描述