如何编写 Python 文档生成器

EdisonStuar 7年前
   <p>在我刚开始接触Python的日子里,我最喜欢做的事情之一是坐在解释器旁使用内置help功能来检查类和方法,决定下一个要敲的内容。这个功能导入一个对象,遍布它的成员,取出文档注释,生成一个类似manpage的输出,从而帮助你找到如何使用正在检查的对象的方法。</p>    <p>它被内置成一个标准库的美妙之处在于通过代码直接生成输出,它为我这样的懒人间接地强调了一个编码风格,我就想着在尽量少做额外的工作的情况下维护文档。尤其是如果你已经为你的变量和函数选择直接的名字。 这种风格涉及到向你的函数和类添加文档字符串,以及通过用下划线前缀来正确地识别私有成员和受保护成员。</p>    <pre>  <code class="language-python">Help on class list in module builtins:    class list(object)   |  list() -> new empty list   |  list(iterable) -> new list initialized from iterable's items   |   |  Methods defined here:   |   |  __add__(self, value, /)   |      Return self+value.     ...      |  __iter__(self, /)   |      Implement iter(self).    ...     |  append(...)   |      L.append(object) -> None -- append object to end   |   |  extend(...)   |      L.extend(iterable) -> None -- extend list by appending elements from the iterable   |   |  index(...)   |      L.index(value, [start, [stop]]) -> integer -- return first index of value.   |      Raises ValueError if the value is not present.     ...      |  pop(...)   |      L.pop([index]) -> item -- remove and return item at index (default last).   |      Raises IndexError if list is empty or index is out of range.   |   |  remove(...)   |      L.remove(value) -> None -- remove first occurrence of value.   |      Raises ValueError if the value is not present.     ...      |  ----------------------------------------------------------------------   |  Data and other attributes defined here:   |   |  __hash__ = None</code></pre>    <p>在Python解释器上运行help(list)的输出。</p>    <p>帮助功能实际上是使用 pydoc 模块生成其输出,它也可以从命令行运行,以产生您路径中任何可导入模块的文本或 html 表示。</p>    <p>不久以前,我需要编写更细致,更正式的设计文档。而作为一个 Markdown 的粉丝,我决定玩一玩mkdocs,看看是否能获得我想要的结果。这个模块可以很容易地将你的 markdown 文档转化为一个样式美观的页面,并且,在发布为官方文档之前,允许你对其做更改。它提供了一个 readthedocs  模板,深圳还提供了一个简单的命令行界面,来把你的修改推送到  GitHub Pages  里面。</p>    <p>在完成了我最初的描述设计决策和注意事项的文本后,我想加上一些细节,描述我正在开发的实际接口方法。因为我已经为大部分的功能写了定义,我想从源代码自动生成参考页面,还希望这个能在 markdown 里面。这样的话,只要我想跑 mkdocs,它就可以连同我文档的其余部分,一起渲染成 html。</p>    <p>然而,事实上还没有一种从源码生成 markdown 的默认方式,除了一些插件。后来,我不断在谷歌上查询,我还是不满意我发现的插件——很多东西都过时了,没有人维护了,或者输出的东西不是我需要的——因此,我决定写一个我自己的项目。我认为这很有意思,这也让我学到了更多关于构建和调试一个模块的知识,更多内容可以查看我之前的文章( 设计一个简单的图形 Python 调试器 ):inspect 模块。</p>    <p>“inspect 模块提供了几个有用的函数来帮助我们获取生存着的对象信息...  ” — Python 文档</p>    <p>检查!</p>    <p>Inspect,源自于标准程序库,它不仅允许你查看较低级别的 python 框架和代码对象,它还提供很多方法来检查模块和类,帮你发现可能感兴趣的的项目。这个也就是之前提到的用来生成帮助文件的 pydoc。</p>    <p>浏览一下在线文档,你会发现许多跟我们所做的尝试相关的方法。最重要的几个是getmembers(),getdoc() 和 signature(),还有许多给 getmembers 做滤波器的 is... 功能。拥有这些,我们可以轻易地循环访问很多功能,包括区分生成器和协同程序,并可以按需要递归到任何一个类以及内部。</p>    <p>导入编码</p>    <p>如果我们要去检查一个对象,不管它是什么,第一步要做的是提供一个导入进我们的命名空间的原理。为何要讨论导入呢?这取决于你想要做什么,还有很多需要担心的,包括虚拟环境,自定义代码,标准模块和重命名。情况会容易混淆,搞错的话会需要一些时间去整理清楚。</p>    <p>我们当然还有些选择,更复杂的是直接从pydoc重用 safeimport (),当出现问题时,为我们解决很多特例和ErrorDuringImport类的特别条款。然而,如果我们对我们的环境需要更高的控制,我们自己简单地运行__import__(modulename)也是可能的。</p>    <p>另一个需要记住的是每一个代码的执行路径。可能会用到 sys.path.append() 的一个目录来进入我们寻找的模块。我的用例 我的用例是从命令行和被检查的模块的路径中的目录执行,所以,我将当前目录添加到 sys.path,这足以解决典型的导入路径问题。</p>    <p>按照上述方式,我们的导入函数会如下所示:</p>    <pre>  <code class="language-python">def generatedocs(module):      try:          sys.path.append(os.getcwd())        # Attempt import          mod = safeimport(module)        if mod is None:             print("Module not found")                  # Module imported correctly, let's create the docs          return getmarkdown(mod)    except ErrorDuringImport as e:          print("Error while trying to import " + module)</code></pre>    <p>决定输出</p>    <p>在继续之前,你需要一个关于如何组织生成 markdown 输出的心理图像。思考:你需要一个不递归到自定义类的浅的引用吗?我们想要包含哪些方法?内置功能会怎么样?是用_还是__方法?我们应该如何呈现函数签名?我们应该拉注释吗?</p>    <p>我的选择如下:</p>    <ul>     <li> <p>每个运行一个 .md 文件,其中包含递归到正在检查的对象的任意子类中生成的信息。</p> </li>     <li> <p>只包括我创建的自定义代码,没有来自导入的模块的信息。</p> </li>     <li> <p>每一项的输出必须用第二级 markdown 标题(##)标识。</p> </li>     <li> <p>所有头文件必须包含正在描述的项的完整路径(module.class.subclass.function)。</p> </li>     <li> <p>将完整的函数签名作为预格式化文本。</p> </li>     <li> <p>为每个标题提供锚点,以便轻松的链接到文档及文档本身内容。</p> </li>     <li> <p>任何以_或者__开头的函数都不做文档记录。</p> </li>    </ul>    <p>整合在一起</p>    <p>一旦对象被导入,我们可以开始检测了。这是一个简单的例子,重复调用 getmembers(object, filter),过滤器是一个有用的 is 函数。你能够发现 isclass 和 isfunction,其它相关的方法都是 is开头的,例如,ismethod ,  isgenerator ,  iscoroutine。这都取决于你是否想写一些通用的,可以处理所有的特殊情况,或一些更小的和更特殊的源代码。我坚持前两点,因为我不用把采用3个不同方法来创建我想要的格式化模块,类和功能。</p>    <pre>  <code class="language-python">def getmarkdown(module):      output = [ module_header ]      output.extend(getfunctions(module)      output.append("***\n")      output.extend(getclasses(module))      return "".join(output)def getclasses(item):      output = list()    for cl in inspect.getmembers(item, inspect.isclass):        if cl[0] != "__class__" and not cl[0].startswith("_"):            # Consider anything that starts with _ private              # and don't document it              output.append( class_header )              output.append(cl[0])                 # Get the docstring              output.append(inspect.getdoc(cl[1])            # Get the functions              output.extend(getfunctions(cl[1]))            # Recurse into any subclasses              output.extend(getclasses(cl[1])    return outputdef getfunctions(item):    for func in inspect.getmembers(item, inspect.isfunction):          output.append( function_header )          output.append(func[0])        # Get the signature          output.append("\n```python\n)          output.append(func[0])          output.append(str(inspect.signature(func[1]))          # Get the docstring          output.append(inspect.getdoc(func[1])      return output</code></pre>    <p>当要格式化大文本和一些编程代码的混合体时,我倾向于把它作为一个在列表或元组中的独立项目,用 "".join() 来合并输出。在写作的时候,这种方法其实比基于插值的方法(.format 和 %)更快。然而,python 3.6 的新字符串格式化将比这更快,更具可读性。</p>    <p>你可以看到,getmembers() 返回一个元组与对象的名称在第一位置和第二位置的实际对象,我们可以用递归遍历对象层次。</p>    <p>对于检索到的每一个项目,可能使用 getdoc() 或 getcomments() 获取文档字符串和注释。对于每一个功能,我们可以使用 signature() 得到 Signature 对象 ,它表示其位置参数和关键字参数的默认值和任何注释,为我们提供了产生简单直接的描述和良好风格的文本,有助于我们理解用户我们写代码的意图。</p>    <p>其他考虑因素和非预期后果</p>    <p>请注意,上面的代码只是示例代码,只是让你大概真的最终产品应该是什么样子。在最终确定产品之前,还有很多其他注意事项:</p>    <ul>     <li> <p>getfunctions 和 getclasses 将显示模块中导入的所有方法和类。包括内置程序包,以及来自外部软件包的任何东西,所以你必须过滤掉更多的 for 循环。我在检查过程中使用模块的 __file__ 属性,不管它包含什么项。换句话说,如果项在我正在执行的路径中存在的模块内定义,则包含它(使用 os.path.commonprefix())。</p> </li>     <li> <p>有一些 gotcha 的文件路径,导入层次结构和名称。像通过 __init__.py 将 moduleX 导入到包中时,你可以通过 package.moduleX.function 访问他的函数方法,但是全称将会是 package.moduleX.moduleX.function—通过 moduleX.__name__ 返回的名称。你或许不在乎这个区别,但是我在乎,所以这是在迭代过程中需要记住的事情。</p> </li>     <li> <p>你会从内置程序库中导入类和任何其他不包含 __file__ 的东西,如果你进行任何如上所述的过滤,那么检查是必要的。</p> </li>     <li> <p>因为这是 markdown,而我们只是导入 docstrings,你可以在你的 docstrings 中包含 mardown 语法,它会美观漂亮的呈现在页面中。然而,这意味着你应该注意正确的转义 docstrings,这样他才不会破坏生成的 HTML。</p> </li>    </ul>    <p>示例输出</p>    <p>我在 sofi 包-精确的说是 sofi.app 模块运行生成器,下面是它创建的 markdown 内容。</p>    <pre>  <code class="language-python"># sofi<a name="sofi"></a><a name="sofi.__init__"></a>### [sofi](#sofi).\_\_init\_\_  ```python  __init__(self)  ```  <a name="sofi.addclass"></a>  ### [sofi](#sofi).addclass```python  addclass(self, selector, cl)```  Add the given class from all elements matching this selector.</code></pre>    <p>下面是通过 mkdocs 运行它产生 readthedocs 主题页面后的最终结果(不包括函数注释)的示例。</p>    <p style="text-align:center"><img src="https://simg.open-open.com/show/cc69bb3195fd3dd0424e10303637663b.png"></p>    <p>我相信你已经知道,使用这些机制自动生成文档,会生成完整、精确和最新的模块信息,这些信息在你编写代码的时候可以进行维护和编写,且操作简单 。我强烈建议每个人都试一试。</p>    <p>在结束之前,我想再补充一点,mkdocs 并不是唯一的文档包,还有其他一些使用广泛的系统,如 Sphinx(mkdocs 基于此开发 )和 Doxygen,他们都能实现我们以上讨论的事项。然而,我比较通过练习来学习和了解更多关于 Python 内部机制和其随附的工具。</p>    <p> </p>    <p>来自:https://www.oschina.net/translate/python-introspection-with-the-inspect-module</p>    <p> </p>