如何编写 Python 文档生成器

在我刚开始接触Python的日子里,我最喜欢做的事情之一是坐在解释器旁使用内置help功能来检查类和方法,决定下一个要敲的内容。这个功能导入一个对象,遍布它的成员,取出文档注释,生成一个类似manpage的输出,从而帮助你找到如何使用正在检查的对象的方法。

它被内置成一个标准库的美妙之处在于通过代码直接生成输出,它为我这样的懒人间接地强调了一个编码风格,我就想着在尽量少做额外的工作的情况下维护文档。尤其是如果你已经为你的变量和函数选择直接的名字。 这种风格涉及到向你的函数和类添加文档字符串,以及通过用下划线前缀来正确地识别私有成员和受保护成员。

Help style="color: #333333; font-weight: bold;">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