如何将Python文件的文档字符串转换为HTML

Question

有没有简单的方法可以把一个 .py 文件转换成 HTML 格式，显示里面的函数接口和 docstring（文档字符串）呢？我查了一下 Sphinx，感觉它是为大项目准备的。我只是想找到一种方法，从一个 .py 文件中提取出函数定义和 docstring 来生成 HTML。

Answer 1

你可以不使用任何工具来完成这个任务。首先，你需要获取数据。下面是一个非常基础的例子：

"""My module"""

def foo():
    """Some function"""
    pass

def bar():
    """Another function"""
    pass

class Spam(object):
    """Some object"""
    pass

if __name__ == '__main__':
    import types

    defs = set(locals().keys()).difference(set(__builtins__.keys())) 

    if __doc__:
        print 'Module:'
        print __doc__, '\n'

    for name in defs:
        object_ = locals()[name]
        if type(object_) is types.FunctionType:
            print "Function %s:" % object_.__name__
            print object_.__doc__, '\n'
        elif type(object_) is type:
            print "Class %s:" % object_.__name__
            print object_.__doc__, '\n'

输出结果将会是：

Module:
My module 

Function bar:
Another function 

Class Spam:
Some object 

Function foo:
Some function 

要获取HTML，你可以使用一个模板引擎，比如Mako。你只需要创建一个模板，然后把数据从__doc__传递给它，这样就可以了。

编辑：这里有一种获取函数签名的方法：

>>> def foo(spam, eggs):
...     bar = spam + eggs
...     return bar
>>> varnames = foo.func_code.co_varnames
>>> argcount = foo.func_code.co_argcount
>>> '%s(%s)' % (foo.__name__, ', '.join(varnames[:argcount]))
0: 'foo(spam, eggs)'

Answer 2

我手写的API文档处理器大致是这样的。

import inspect
inspect.getmembers(MyClass, predicate=inspect.ismethod)

它会给你返回一个所有可用方法的列表。第一个对象是方法名称的字符串表示，这样你就可以用简单的过滤函数来筛选出你需要的方法。我的API会过滤掉那些以_开头的方法（这些是内部方法，不能通过API访问），比如：

    filter(lambda x: not x.startswith('_'), [x[0] for x in inspect.getmembers(MyClass, predicate=inspect.ismethod)])

第二个对象是相关方法的实例方法。你可以用它来调用__doc__来获取文档字符串，或者调用任何你可以用方法实例来调用的其他方法。

for item in inspect.getmembers(MyClass, predicate=inspect.ismethod):
    print item[0]
    print item[1].__doc__