Question

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

Answer 1

如果你真的想使用Pydoc，你可以在终端中进行：

$ pydoc -w myproject

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

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

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

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

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

Answer 2

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

$ pydoc myproject > helpfile.txt

此文件可以打印或上传到Github而无需太多额外工作。