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

约定不等于承诺〃 2024-03-29 16:21 15阅读 0赞

要从文档字符串创建文档，我们可以使用以下包和模块 -

*  pydoc
 *  epydoc
 *  Sphinx

让我们一一了解它们——

### pydoc ###

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

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

对于模块、类、函数和方法，显示的文档派生自对象的文档字符串（即 \_\_doc\_\_ 属性），并递归派生自其可记录成员。如果没有文档字符串，pydoc 会尝试从源文件中类、函数或方法定义正上方或模块顶部的注释行块中获取描述（请参阅 inspect.getcomments（））。

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

pydoc sys

在 shell 提示符下将显示 sys 模块上的文档，其样式类似于 Unix man 命令显示的手册页。pydoc 的参数可以是函数、模块或包的名称，也可以是对模块或包中的模块中的类、方法或函数的虚线引用。

您还可以使用 pydoc 在本地计算机上启动 HTTP 服务器，该服务器将为访问的 Web 浏览器提供文档。

*  pydoc -n <主机名> 将启动服务器侦听给定的主机名。默认情况下，主机名为“localhost”，但如果您希望从其他计算机访问服务器，则可能需要更改服务器响应的主机名。
 *  pydoc -b 将启动服务器，并另外打开一个 Web 浏览器到模块索引页。

### epydoc ###

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

Epydoc是一个工具，用于根据Python模块的文档字符串生成API文档。有关 epydoc 输出的示例，请参阅 epydoc 本身的 API 文档（html、pdf）。一种名为 epytext 的轻量级标记语言可用于格式化文档字符串，并添加有关特定字段（如参数和实例变量）的信息。Epydoc 还可以理解用 reStructuredText、Javadoc 和 plaintex 编写的文档字符串。

### Sphinx ###

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

*  输出格式 - HTML（包括Windows HTML帮助），LaTeX（用于可打印的PDF版本），ePub，Texinfo，手册页，纯文本。
 *  广泛的交叉引用 - 函数、类、引文、词汇表术语和类似信息的语义标记和自动链接。
 *  分层结构 - 文档树的简单定义，具有与兄弟姐妹，父母和孩子的自动链接。
 *  自动索引 − 通用索引以及特定于语言的模块索引。
 *  代码处理 - 使用Pygments荧光笔自动突出显示。
 *  扩展 - 自动测试代码片段，通过内置扩展包含来自Python模块的文档字符串，以及通过第三方扩展的更多功能。
 *  主题 - 通过创建主题来修改输出的外观，并重用许多第三方主题。
 *  贡献的扩展 - 用户贡献的数十个扩展;它们中的大多数都可以从PyPI安装。