如何使用Pydoc生成文档 [英] How to generate documentation using Pydoc

问题描述

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

I need to generate documentation from comments using pydoc. What are the basic steps to do that?

推荐答案

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

If you really want to use Pydoc, you can simply do in a terminal:

$ pydoc -w myproject

此会从命令生成老式的HTML文档。
请注意，Pydoc是从2.1开始在Python中用于 help（）函数的模块。
它将检索不是注释的 docstrings 。您应该使用docstrings来描述函数。

This will generate an old-school HTML documentation from doctrings. Note that Pydoc is the module used in Python since 2.1 for the help() function. It will retrieve the docstrings which are NOT comments. You should describe your functions using docstrings.

但这是一种古老的方法，使用Pydoc生成文档。
在Python中执行此操作的流行工具是 Sphinx 。但是，您需要将文档字符串的格式设置为reStructuredText。

But it is a kind of old-school using Pydoc for documentation generating. The popular tool to do that in Python is Sphinx. But you'll need to format your docstrings in a particular format as reStructuredText.

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

You could also use pdoc, which auto-extracts documentation from your docstrings (i.e. public API) and supports markdown, numpydoc, google-style docstrings format and some reStructuredText directives.

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

Have a look here to get some information concerning docstrings formatting.

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

You can also use Pyment to generate docstring skeletons or convert existing ones to a particular format.

这篇关于如何使用Pydoc生成文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！