如何在 Python 中从文档字符串创建文档?
要从文档字符串创建文档，我们可以使用以下包和模块 -
- Pydoc
- Epydoc
- Sphinx
让我们逐一了解它们 -
Pydoc
pydoc 模块可以从 Python 源代码中的文档字符串创建 HTML。
pydoc 模块自动从 Python 模块生成文档。文档可以作为文本页面显示在控制台上，提供给 Web 浏览器或保存到 HTML 文件中。
对于模块、类、函数和方法，显示的文档来自对象的文档字符串(即 __doc__ 属性)，并递归地从其可记录成员中派生。如果没有文档字符串，pydoc 会尝试从源文件中类、函数或方法定义上方或模块顶部的注释行块中获取描述(请参阅 inspect.getcomments())。
内置函数 help() 调用交互式解释器中的在线帮助系统，该系统使用 pydoc 将其文档生成为控制台上的文本。通过在操作系统的命令提示符下运行 pydoc 作为脚本，也可以从 Python 解释器外部查看相同的文本文档。例如，在 shell 提示符下运行 -
pydoc sys
将显示有关 sys 模块的文档，其样式类似于 Unix man 命令显示的手册页。 pydoc 的参数可以是函数、模块或包的名称，也可以是包中模块或模块内的类、方法或函数的点引用。
您还可以使用 pydoc 在本地计算机上启动 HTTP 服务器，该服务器将为访问的 Web 浏览器提供文档。
pydoc -n <hostname> 将启动在给定主机名上监听的服务器。默认情况下，主机名是"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 安装。
