python - 如何使用 Pydoc 生成文档

Question

我需要使用 pydoc 从评论中生成文档。这样做的基本步骤是什么？

Answer 1

如果你真的想使用 Pydoc，你可以简单地在终端中做：

$ pydoc -w myproject

这将从 docstrings 生成一个老式的 HTML 文档。请注意，Pydoc 是 Python 2.1 以来用于该help()函数的模块。它将检索不是注释的文档字符串。您应该使用文档字符串来描述您的函数。

但它是一种使用 Pydoc 生成文档的老派。在 Python 中执行此操作的流行工具是Sphinx。但是您需要将文档字符串以特定格式格式化为 reStructuredText。

您还可以使用pdoc，它从您的文档字符串（即公共 API）中自动提取文档，并支持 markdown、numpydoc、google 样式的文档字符串格式和一些 reStructuredText 指令。

在这里查看以获取有关文档字符串格式的一些信息。

您还可以使用Pyment生成文档字符串骨架或将现有的骨架转换为特定格式。

Answer 2

或者，如果您想要一个简单的文本文件而不是 HTML，您可以使用以下简单命令将控制台输出重定向到一个文件：

$ pydoc myproject > helpfile.txt

这个文件可以打印或上传到 Github，而不需要太多额外的努力。