本文主要是介绍python pydoc-文档生成工具(汇总tcy)，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！
pydoc-文档生成工具 2018/9/8
------------------------------------------------------------------------------
1.1.用途：
是python自带的一个文档生成工具，使用pydoc可以很方便的查看类和方法结构
python中pydoc模块可以从python代码中获取docstring，然后生成帮助信息。
主要用于从python模块中自动生成文档，这些文档可以基于文本呈现的、也可以生成WEB 页面的，还可以在服务器上以浏览器的方式呈现！
pydoc - Python文档工具
-------------------------------------------------------------------------------
1.2.方法：
pydoc <name> ...
显示关于某事的文本文档。 <name>可以是a的名称 Python关键字，主题，功能，模块或包，或点缀引用模块或模块中的类或函数包。
如果<name>包含'\\'，则将其用作a的路径 Python源文件到文档。如果名称是'关键字'，'主题'，或“模块”，显示这些内容的列表。
pydoc -k <keyword>
在所有可用模块的概要行中搜索关键字。
pydoc -n <hostname>
使用给定的主机名启动HTTP服务器（默认值：localhost）。
pydoc -p <port>
在本地计算机上的给定端口上启动HTTP服务器。港口
数字0可用于获取任意未使用的端口。
pydoc -b
在任意未使用的端口上启动HTTP服务器并打开Web浏览器
以交互方式浏览文档。此选项可用于与-n和/或-p组合。
pydoc -w <name> ...
将模块的HTML文档写入当前文件目录。如果<name>包含'\\'，则将其视为文件名;
如果它命名一个目录，为所有内容编写文档。
------------------------------------------------------------------------------
2.查看文档方法
2.1.启用服务器查看
方法1：启动本地服务，在web上查看文档
C:\Users\Administrator>python -m pydoc -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
方法2：通过http://localhost:1234来访问查看文档
说明：
1、-p指定启动服务的端口号，可以随意指定不冲突端口号
2、只有在自建的工程根目录下使用该命令，才能看到当前工程下所有的内容，否则只能看到python环境变量下的模块内容
3、如果本地只有一个python，可以直接使用【pydoc -p 端口号】启动，但因为我本地有python2和python3，所以指定了用python3
-------------------------------------------------------------------------------
2.2.直接查看*.py文件内容
步骤1：新建文件c:\python37\lib\test_pydoc.py
见下文：实例代码
步骤2：进入testpydoc.py所在目录
C:\Users\Administrator>cd c:\python37\lib
步骤3：运行
C:\python37\lib\>python -m pydoc test_pydoc
步骤4：显示
见下文：显示”直接查看test_pydoc.py文件内容 ”
c:\python37\Lib>
-------------------------------------------------------------------------------
2.3.生成html说明文档
运行：
c:\python37\Lib>python -m pydoc -w test_pydoc
显示：
wrote test_pydoc.html
说明：在c:\python37\Lib\test_pydoc.html文档已经生成；和上面的查看内容相同；
默认将当前目录下的testpydoc生成一个叫做testpydoc.html的文档，如果是目录直接【python3 -m pydoc -w 目录名】生成文档
如果是将整个目录生成这种格式，不建议用这种方式，因为如果他展示目录下的子文件的说明时，会去子目录下找对应.html文件，如果文件不存在，就会404
-------------------------------------------------------------------------------
2.4.-k查找模块
用途：
py通过-k查找模块，会在当前工程目录以及python环境变量目录下查找包含关键词的模块信息
命令：
c:\python37\Lib>python -m pydoc -k test_pydoc
显示：
test.pydoc_mod - This is a test module for test_pydoc
test.test_pydoc
test_pydoc - @filename: c:\python\lib\ test_pydoc.py
-------------------------------------------------------------------------------
3.1.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的变量
------------------------------------------------------------------------------
3.2.注释方法
python注释方法：
单行注释：使用#号进行注释
多行注释：使用三个双引号或单引号来注释多行内容
pydoc注释展示策略：
在functions和classes前面加#注释，或者在function和class第一行内加三个单引号或三个双引号进行注释
如果有三个引号的注释方法，会优先使用三个点的注释，其次才展示#号的注释
注意：如果在方法或class定义后第一行使用#注释是拉取不到注释的
----------------------------------------------------------------------------
4.1.示例代码：
"""
@filename: c:\python\lib\ test_pydoc.py
@author tcy1
@desc 本模块是一个测试文件说明pydoc读取内容
@date 2018/9/13
说明：
classes: MyClass()
Method: class_fun1();class_fun2();class_fun3()
function: tun1()，fun2()，fun3()
Data：a，b , c1, g1
"""
#filename: c:\python\lib\ test_pydoc.py
#模块开头单行注释和多行注释只能选一个最上面的显示
__author__ = "tcy"
#fun1()上的注释：注释放在方法名前用'#'号注释
def fun1(a):
a=100
print("注释放在方法名前",a)
#fun2()上的注释：由于下面有多行注释，本行不会被显示
def fun2():
"""
fun2()多行注释；优先显示；
"""
print("既有'#'号又有多行注释时，优先展示多行注释 ")
def fun3():
#在方法第一行内使用'#'注释不生效
print("在方法内使用#号注释，不生效")
#Myclass 类上注释，由于有多行注释，本行不会显示
class MyClass():
"""
1.注释生效顺序与方法一致，优先展示类下的多行注释
2.如没多行注释，显示类上面的 ‘#’ 号注释
"""
g1=200#变量注释不会显示
def __init__(self,x,y):
self.x=x #变量注释不会显示
self.y=y #变量注释不会显示
#class_fun1 ()单行注释不显示
def class_fun1(self):#类下方法的注释不会展示
""" class_fun1 ()多行注释"""
print("类下的第一个方法")
# class_fun12()单行注释
def class_fun2(self,a):
print("类下的第二个参数，包含a参数")
def class_fun3(self):
print("类方法无注释")
a=1 #变量注释不会显示
b=2 #变量注释不会显示
c1=MyClass(1000,-2000) #变量注释不会显示
-------------------------------------------------------------------------------
4.2.显示”直接查看test_pydoc.py文件内容 ”
c:\python37\Lib>python -m pydoc test_pydoc
Help on module test_pydoc:
NAME
test_pydoc
DESCRIPTION
@filename: c:\python\lib\ test_pydoc.py
@author tcy1
@desc 本模块是一个测试文件说明pydoc读取内容
@date 2018/9/13
说明：
classes: MyClass()
Method: class_fun1();class_fun2();class_fun3()
function: tun1()，fun2()，fun3()
Data：a，b , c1, g1
CLASSES
builtins.object
MyClass
class MyClass(builtins.object)
| MyClass(x, y)
|
| 1.注释生效顺序与方法一致，优先展示类下的多行注释
| 2.如没多行注释，显示类上面的 ‘#’ 号注释
|
| Methods defined here:
|
| __init__(self, x, y)
| Initialize self. See help(type(self)) for accurate signature.
|
| class_fun1(self)
| class_fun1 ()多行注释
|
| class_fun2(self, a)
| # class_fun12()单行注释
|
| class_fun3(self)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| g1 = 200
FUNCTIONS
fun1(a)
#fun1()上的注释：注释放在方法名前用'#'号注释
fun2()
fun2()多行注释；优先显示；
fun3()
DATA
a = 1
b = 2
c1 = <test_pydoc.MyClass object>
AUTHOR
tcy
FILE
c:\python37\lib\test_pydoc.py
-------------------------------------------------------------------------------
这篇关于python pydoc-文档生成工具(汇总tcy)的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！
