要从文档字符串创建文档,我们可以使用以下包和模块 -
- 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安装。