如何从 Python 中的文档字符串创建文档？

我们可以使用以下软件包和模块从文档字符串中创建文档：

• Pydoc
• Epydoc
• Sphinx

接下来让我们一个一个来了解它们：

Pydoc

pydoc 模块可以从 Python 源代码中的文档字符串创建 HTML 文档。

pydoc 模块可以自动从 Python 模块生成文档。文档可以作为文本页面在控制台上显示，可以提供给 Web 浏览器访问或者保存为 HTML 文件。

对于模块、类、函数和方法，显示的文档是从对象的文档字符串（即 doc 属性）以及递归地从其可记录的成员中派生的。如果没有文档字符串，pydoc 会尝试从源文件中定义类、函数或方法的上方的注释行块中获取描述，或在模块的顶部获取描述（参见 inspect.getcomments()）。

内置函数 help() 在交互式解释器中调用在线帮助系统，该系统使用 pydoc 生成其文本形式的文档。可以通过在操作系统的命令提示符下将 pydoc 作为脚本运行，也可以从 Python 解释器外部查看相同的文本文档。例如，在 Shell 提示符下运行：

pydoc sys

将以与 Unix man 命令显示的手册页面类似的样式，显示 sys 模块的文档。参数可以是函数、模块或包的名称，也可以是模块或包中某个类、方法或函数的点分引用。

您还可以使用 pydoc 启动在本地计算机上提供文档服务给用户的 HTTP 服务器。

• pydoc -n <主机名> 将在指定的主机名上启动服务器。默认情况下，主机名是 ‘localhost’，但如果要从其他计算机访问服务器，则可能需要更改服务器响应的主机名。

• pydoc -b 将启动服务器，并额外打开一个 web 浏览器到模块索引页面。

Epydoc

使用 epydoc 软件包纯粹从文档字符串创建 API 文档。

Epydoc 是一个基于文档字符串为 Python 模块生成 API 文档的工具。可以使用名为 epytext 的轻量级标记语言来格式化文档字符串，并添加有关特定字段的信息，例如参数和实例变量。Epydoc 还能理解以 reStructuredText、Javadoc 和 plaintext 编写的文档字符串。

Sphinx

Sphinx 使创建智能和美观的文档变得容易。以下是其特点。

• 输出格式 – HTML（包括Windows HTML Help），LaTeX（用于可打印的PDF版本），ePub，Texinfo，纯文本。

• 广泛的交叉引用 – 对于函数、类、引用、词汇表术语和类似信息的语义标记和自动链接。

• 层次结构 – 定义文档树很容易，可以自动链接到兄弟、父母和子代。

• 自动索引 – 一般的索引以及特定于语言的模块索引。

• 代码处理 – 使用Pygments高亮显示器自动突出显示。

• 扩展 – 自动测试代码片段，在Python模块中包含docstrings的内置扩展，以及通过第三方扩展提供的更多功能。

• 主题 – 通过创建主题修改输出的外观和感觉，并重复使用许多第三方主题。

• 贡献扩展 – 很多用户贡献的扩展，其中大多数可以从PyPI安装。