你可以看到,getmembers() 返回一个元组与对象的名称在第一位置和第二位置的实际对象,我们可以用递归遍历对象层次。
对于检索到的每一个项目,可能使用 getdoc() 或 getcomments() 获取文档字符串和注释。对于每一个功能,我们可以使用 signature() 得到 Signature 对象 ,它表示其位置参数和关键字参数的默认值和任何注释,为我们提供了产生简单直接的描述和良好风格的文本,有助于我们理解用户我们写代码的意图。
其他考虑因素和非预期后果
请注意,上面的代码只是示例代码,只是让你大概真的最终产品应该是什么样子。在最终确定产品之前,还有很多其他注意事项:
getfunctions 和 getclasses 将显示模块中导入的所有方法和类。包括内置程序包,以及来自外部软件包的任何东西,所以你必须过滤掉更多的 for 循环。我在检查过程中使用模块的 __file__ 属性,不管它包含什么项。换句话说,如果项在我正在执行的路径中存在的模块内定义,则包含它(使用 os.path.commonprefix())。
有一些 gotcha 的文件路径,导入层次结构和名称。像通过 __init__.py 将 moduleX 导入到包中时,你可以通过 package.moduleX.function 访问他的函数方法,但是全称将会是 package.moduleX.moduleX.function—通过 moduleX.__name__ 返回的名称。你或许不在乎这个区别,但是我在乎,所以这是在迭代过程中需要记住的事情。
你会从内置程序库中导入类和任何其他不包含 __file__ 的东西,如果你进行任何如上所述的过滤,那么检查是必要的。
因为这是 markdown,而我们只是导入 docstrings,你可以在你的 docstrings 中包含 mardown 语法,它会美观漂亮的呈现在页面中。然而,这意味着你应该注意正确的转义 docstrings,这样他才不会破坏生成的 HTML。
示例输出
我在 sofi 包-精确的说是 sofi.app 模块运行生成器,下面是它创建的 markdown 内容。
# sofi<a name="sofi"></a><a name="sofi.__init__"></a>### [sofi](#sofi).\_\_init\_\_```python__init__(self)```<a name="sofi.addclass"></a>### [sofi](#sofi).addclass```pythonaddclass(self, selector, cl)```Add the given class from all elements matching this selector