如何编写 Python 文档生成器

我们当然还有些选择，更复杂的是直接从pydoc重用 safeimport ()，当出现问题时，为我们解决很多特例和ErrorDuringImport类的特别条款。然而，如果我们对我们的环境需要更高的控制，我们自己简单地运行__import__(modulename)也是可能的。

另一个需要记住的是每一个代码的执行路径。可能会用到 sys.path.append() 的一个目录来进入我们寻找的模块。我的用例 我的用例是从命令行和被检查的模块的路径中的目录执行，所以，我将当前目录添加到 sys.path，这足以解决典型的导入路径问题。

按照上述方式，我们的导入函数会如下所示：

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)

决定输出

在继续之前，你需要一个关于如何组织生成 markdown 输出的心理图像。思考：你需要一个不递归到自定义类的浅的引用吗？我们想要包含哪些方法？内置功能会怎么样？是用_还是__方法？我们应该如何呈现函数签名？我们应该拉注释吗？

我的选择如下：

• 每个运行一个 .md 文件，其中包含递归到正在检查的对象的任意子类中生成的信息。

• 只包括我创建的自定义代码，没有来自导入的模块的信息。

• 每一项的输出必须用第二级 markdown 标题（##）标识。

• 所有头文件必须包含正在描述的项的完整路径（module.class.subclass.function）。

• 将完整的函数签名作为预格式化文本。

• 为每个标题提供锚点，以便轻松的链接到文档及文档本身内容。

• 任何以_或者__开头的函数都不做文档记录。

   3/6   首页 上一页 1 2 3 4 5 6 下一页 尾页