python文档生成工具-pydoc

为了找到对象及其文档内容，pydoc 会导入文档所在的模块。 因此，任何模块层级的代码都将被执行。 请使用 if __name__ == '__main__': 语句来确保一个文件的特定代码仅在作为脚本被发起调用时执行而不是在被导入时执行。

 

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

和 help() 及 __doc__ 不同，使用 pydoc 模块无需编写任何 python 代码，通过执行 python 命令即可查看程序中成员的说明性文档。

python -m pydoc 模块名

其中，-m 表示运行指定模块，这里表示要执行 pydoc 模块。注意在指定模块名时，除非其创建在 Python 解释器能自行找到的目录下，否则这里要明确模块所在的位置。

 

python -m pydoc demo

执行此命令，即可看到 demo.py 文件中 display() 函数、my_cla 类以及该类中 say() 实例方法的说明性文档。

 

pydoc 还可以将指定模块的帮助信息提取出来，并自动组织成一个 HTML 文档。

python -m pydoc -w 模块名

上面命令主要就是为 pydoc 模块额外指定了 -w 选项，该选项代表 write，表明输出 HTML 文档。

例如，在 demo.py 所在当前目录下运行如下命令：

python -m pydoc -w demo

运行上面命令，可以看到系统生成“wrote demo.html” 提示信息。接下来可以在该目录下发现额外生成了一个 demo.html 文件，使用浏览器打开该文件

 

pydoc 模块还可以查看当前操作系统中所有 Python 模块的 HTML 文档信息，有以下 2 种方式：

python -m pydoc -p 端口号
python -m pydoc -b

这 2 种方式是非常类似的，它们的区别是：前者使用指定的端口启动 HTTP 服务器，而后者将任意选择一个未被占用的端口来启动 HTTP 服务器。

通过执行它们中的任意一个，都会打开浏览器并显示出一个包含所有 Pyhton 模块的 HTML 文档。

举个例子，执行如下命令：

python -m pydoc -p 8888

Server ready at http://localhost:8888/
Server commands: [b]rowser, [q]uit
server>

这里需要我们手动输入 b 或 q。其中，b 命令表示启动浏览器，而 q 命令表示退出。

输入b 浏览器会自动打开并自动访问 http://localhost:8888/

在该页面中，如果想查看某个模块的说明文档，直接点击该模块即可

 

pydoc 还提供了一个 -k 选项，该选项可以找到名称中包含执行字符串的所有模块

python -m pydoc -k 模块名

例如，在 demo.py 所在目录下运行如下命令：

python -m pydoc -k demo

......
demo

可以看到，pydoc 找到了所有包含“demo”的模块名，当然也包括我们自己创建的 demo.py。

 

 

windows:

python -m pydoc name

linux:

pydoc name

D:\>python -m pydoc <modulename>   # 比如说: python -m pydoc math

pydoc server ready at http://localhost:8888/

还可以使用 pydoc 在本机上启动一个 HTTP 服务，这将向来访的 Web 浏览器提供文档服务。 pydoc -p 8888 将在 8888 端口上启动 HTTP 服务，
允许你在你喜欢的 Web 服务器中通过 http://localhost:8888/ 浏览文档内容。 指定 0 作为端口号将会任意选择一个未使用的端口。

帮助

pydoc -h

import pydoc
if __name__ == '__main__':
pydoc.cli()

 

 

核心模块的模块文档位置对应于 https://docs.python.org/X.Y/library/ 其中 X 和 Y 是 Python 解释器的主要版本号和小版本号。

这可通过设置 PYTHONDOCS 环境变量来重载为指向不同的 URL 或包含 Library Reference Manual 页面的本地目录