pydoc

今天玩了下pydoc,还挺爽的,记录一下.

pydoc 是python的内建文档工具(貌似是利用python的反射弄的,爽是爽,不过好像对zope等库会有点问题啊)

pydoc的用法

pydoc - the Python documentation tool

pydoc.py <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 __builtin__.str.find 会显示str.find的文档,不过比较郁闷的是直接 pydoc str.find 是不行的...

pydoc.py -k <keyword>

    Search for a keyword in the synopsis lines of all available modules.

pydoc.py -p <port>

    Start an HTTP server on the given port on the local machine.

   在对应port开一个能返回文档的http server,用浏览器访问就可以了

pydoc.py -g

    Pop up a graphical interface for finding and serving documentation.

    超推荐,除了开http server外,还会打开一个小小的图形化搜索工具, 搜索的结果多于一项时,会显示为一个列表,双击列表的一项就会打开浏览器来访问http server来显示相关的文档

  不过貌似搜索功能不怎么样啊,只能直接搜索到module

pydoc.py -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.

   把生成的Html保存成文件而已



pydoc 生成的html的颜色挺不错,就是缺少一些导航的功能,比方说它把一个Module的文档分成Modules,Classes,Functions, Data,几大块,但没有对应的导航链接或锚点,想快速切换很麻烦.看了下源码,发现想改变输出的格式还是比较简单的,为了添加锚点,这样改了一下:

class HTMLDoc(Doc):

......

def bigsection(self, title, *args):

        """Format a section with a big heading."""

#        title = '<big><strong>%s</strong></big>' % title

       title = '<big><strong><a name="%s">%s</a></strong></big>' % (title,title)

        return self.section(title, *args)

这样想快速的跳到Functions部分只需要在浏览器的地址栏里的url后面加上#Functions ,然后按回车就可以了,以后有时间还可以继续优化 :)



另外vim上的pydoc.vim插件也很爽,因为它会直接调用pydoc命令,而我安装的python2.5没有附带它的命令行程序,自己弄了一个放到 python_root:

pydoc.bat:

  d:\%python_root%\Lib\pydoc.py  %*

这样就可以用 PyDocSearch或PyDoc 命令或直接把光标移动到想查询的字符串上按  \pw 来查询了