pydoc是python自带的一个文档生成工具，使用pydoc可以很方便的查看类和方法结构，pydoc模块可以从python代码中获取docstring，然后生成帮助信息。

pydoc是Python自带的模块，主要用于从python模块中自动生成文档，这些文档可以基于文本呈现的、也可以生成WEB页面的，还可以在服务器上以浏览器的方式呈现！

python -m pydoc -p 1234     在本地机器上，按照给定的端口启动HTTP

一、查看文档的方法

方法1：启动本地服务，在web上查看文档

python3 -m pydoc -p 1234

通过http://localhost:1234来访问查看文档

说明：

1、-p指定启动的服务的端口号，可以随意指定不冲突的端口号

2、只有在自建的工程根目录下使用该命令，才能看到当前工程下所有的内容，否则只能看到python环境变量下的模块内容

3、如果本地只有一个python，可以直接使用【pydoc -p 端口号】启动，但因为我本地有python2和python3，所以指定了用python3

方法2：直接查看某个py文件的内容

例子：新建了一个py文件叫做testpydoc.py，进入testpydoc.py所在目录

python3 -m pydoc testpydoc

方法三：生成html说明文档

例子：新建了一个py文件叫做testpydoc.py，进入testpydoc.py所在目录

python3 -m pydoc -w testpydoc

会默认将当前目录下的testpydoc生成一个叫做testpydoc.html的文档，如果是目录直接【python3 -m pydoc -w 目录名】生成文档

说明：如果是将整个目录生成这种格式，不建议用这种方式，因为如果他展示目录下的子文件的说明时，会去子目录下找对应.html文件，如果文件不存在，就会404

方法四：-k查找模块

py通过-k查找模块，会在当前工程目录以及python环境变量目录下查找包含关键词的模块信息 

【python3 -m pydoc -k 关键词】

例如如下命令：

python3 -m pydoc -k  testpydoc

结果如下：

testpydoc - @author 每天1990

二、html文档说明 

通过查看文档的方法，我们可以看到在html的文档主要分成四部分：py文件的顶部注释、Classes、Functions、Data

（示例代码见结尾部分）

第一部分：模块的文档说明，展示模块顶部的多行注释

注释内如果包含了模块文件内的class名，或方法名()，则显示蓝色，且可以点击跳转到对应说明位置

第二部分：classes，展示class以及class下的function

1.只能展示class下的注释，不会展示class下方法的注释

2.class上面有#注释时，展示#号的注释

3.class下有”””多行注释”””时优先展示多行注释，就不展示顶部的#号的注释了

need-to-insert-img

第三部分：function，模块下的def方法，不是class中的方法

1.function上面有#注释时，展示#号的注释

2.function下有”””多行注释”””时优先展示多行注释，就不展示顶部的#号的注释了

第四部分：data，模块下直接定义的变量，不是function或class的变量

示例代码：

"""

@author 每天1990

@desc 本模块是一个测试文件，用来说明pydoc的读取内容

@date 2017/4/13

说明：

classes:testclass()，具有function1()和function2()两个方法

function：test1()，test2()，test3()

Data：a，b

"""

#注释放在方法名前，使用#号注释

def test1(a):

print("注释放在方法名前")

#注释放在方法名前，使用#号注释

def test2():

"""

注释放在方法内的第一行，既有#号又有多行注释时，优先展示多行注释

"""

print("既有#号又有多行注释时，优先展示多行注释 ")

def test3():

#在方法第一行内使用#注释

print("在方法内使用#号注释，不生效")

class testclass():

"""

注释生效顺序与方法一致，优先展示类下的多行注释，如果没有才展示类上面的#号注释

类下的方法的注释不会展示出来

"""

def function1(self):#类下方法的注释不会展示

print("类下的第一个方法")

def function2(self,a):

print("类下的第二个参数，包含a参数")

a=1#变量的注释不会展示出来

b=2

三、注释方法

通过上面的文档说明，我们可以合理的注释，有助于了解工程结构

python的注释方法有两种：

1.单行注释：使用#号进行注释

#单行注释

2.多行注释：使用三个双引号或单引号来注释多行内容

'''

单引号进行多行注释

'''

"""

双引号进行多行注释

"""

pydoc注释展示策略：

在functions和classes前面加#注释，或者在function和class第一行内加三个单引号或三个双引号进行注释

如果有三个引号的注释方法，会优先使用三个点的注释，其次才展示#号的注释

注意：如果在方法或class定义后第一行使用#注释是拉取不到注释的

例子1：class前有#号注释，class内有多行注释，pydoc会优先展示三个点内的注释

例子2：方法内使用#号注释，pydoc不会显示注释内容（class同理）

例子3：方法或class没有多行注释，只在方法外有#号注释时，会展示定义前的#号内的内容

例子4：模块顶部的内容，优先展示多行注释中的内容