在终端上输入pydoc会显示以下信息
pydoc - the Python documentation tool
pydoc <name> ...
Show text documentation on something. <name> may be the name of a
Python keyword, topic, function, module, or package, or a dotted
reference to a class or function within a module or module in a
package. If <name> contains a ‘/‘, it is used as the path to a
Python source file to document. If name is ‘keywords‘, ‘topics‘,
or ‘modules‘, a listing of these things is displayed.
pydoc -k <keyword>
Search for a keyword in the synopsis lines of all available modules.
pydoc -p <port>
Start an HTTP server on the given port on the local machine. Port
number 0 can be used to get an arbitrary unused port.
pydoc -b
Start an HTTP server on an arbitrary unused port and open a Web browser
to interactively browse documentation. The -p option can be used with
the -b option to explicitly specify the server port.
pydoc -w <name> ...
Write out the HTML documentation for a module to a file in the current
directory. If <name> contains a ‘/‘, it is treated as a filename; if
it names a directory, documentation is written for all the contents.
pydoc是python自带的一个文档生成工具,使用pydoc可以很方便的查看类和方法结构
python中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下有”””多行注释”””时优先展示多行注释,就不展示顶部的#号的注释了
第三部分: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:模块顶部的内容,优先展示多行注释中的内容
转载自:https://www.cnblogs.com/meitian/p/6704488.html