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

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

• Pydoc
• Epydoc
• Sphinx

我们依次来了解它们：

Pydoc

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

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

对于模块、类、函数和方法，显示的文档来源于对象的文档字符串（即__doc__属性），以及递归地对可文档化成员进行处理。如果没有文档字符串，则pydoc尝试从源文件中类、函数或方法定义之上的注释块中获取描述，或者从模块的顶部获取描述（参见inspect.getcomments()）。

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

pydoc sys

在shell提示符下，pydoc可以显示sys模块的文档，其风格类似于Unix man命令显示的手册页。pydoc的参数可以是函数、模块或包的名称，或者是模块内或包中类、方法或函数的点引用。

你也可以使用pydoc在本地机器上启动一个HTTP服务器，用于向访问的Web浏览器提供文档。

• pydoc -n <hostname>将在给定的主机名上启动服务器。默认情况下，主机名是“localhost”，但如果你希望其他计算机可以访问该服务器，你可能需要更改服务器响应的主机名。

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

Epydoc

使用epydoc包从docstrings创建API文档。

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

Sphinx

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

• 输出格式-HTML（包括Windows HTML Help）、LaTeX（用于可打印的PDF版本）、ePub、Texinfo、手册页、纯文本。

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

• 分层结构-易于定义文档树，自动链接到同级、父级和子级。

• 自动索引-通用索引以及特定于语言的模块索引。

• 代码处理-使用Pygments高亮自动高亮显示。

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

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

• 贡献的扩展-数十个由用户贡献的扩展；其中大多数可以从PyPI安装。