用pydoc查看导出docstring

代码就是最好的文档。

我们在编码的同时，精心编写维护docstring，就是为了不再写额外的接口文档，通过工具就能够查看或者导出docstring。这个工具就是pydoc，属于python标准库。

用pydoc查看

比如你要查看 sys 模块的docstring：

$ python3 -m pydoc sys

然后你看到的，在python prompt中用help(sys)看到的一样。（help函数也是调用pydoc的接口）

pydoc工具输出的内容，都来自你写的模块的docstring！（如何编写docstring？）

如何用pydoc导出文档？

导出txt文件，就用Linux的重定向：

$ python3 -m pydoc sys > sys.txt

导出html文件：

$ python3 -m pydoc -w sys
wrote sys.html

搜索synopsis

这个synopsis，我测试的结果，就是模块和package的multi-line docstring的第一行：summary。pydoc有一个 -k 参数，可以用某个关键字搜索所有模块的这一行：

$ python3 -m pydoc -k tcl
test.test_tcl 
tkinter - Wrapper functions for Tcl/Tk.
PIL._tkinter_finder - Find compiled module linking to Tcl / Tk libraries

搜索范围除了当前目录下的模块和package，还包括标准库中的！

----

pydoc还可以生成一个http server，让我们通过浏览器查阅docstring，我还没感觉这个有多大用处，设置也很简单，看官方文档吧：https://docs.python.org/3/library/pydoc.html

-- EOF --

相关文章