python - 在 Python 文档中嵌入图像

Question

我有一个 python 项目，我想创建文档...

在本文档中，允许嵌入图像至关重要。另外，我不想创建单独的文件。换句话说：*.py 文件将包含脚本和文档（嵌入了图像）。

当然，稍后此 *.py 将由工具处理以创建降价或 HTML 报告。

我查看了mkDocs和Sphinx，但我不确定它们是否支持这些要求。

有谁知道如何使用这些工具（或其他工具）做类似的事情？

Answer 1

正如@mzjn 建议的那样，您可以在您的python 模块中编写文档字符串。文档字符串可能是有效的 reStructuredText。reStructuredText 语法支持内联图像。图像的给定文件名必须相对于源文件或绝对相对于文档根目录。您必须有一个单独的图像文件。

要使用 Sphinx 构建文档，您将需要一组用于构建文档的 reStructuredText 文件。您可以使用Sphinxquick-start生成 .rst 源文件。

一旦您编写了文档字符串，并创建了 .rst 源文件，并将您配置conf.py为使用autodoc模块来提取模块的文档字符串，那么您就可以使用 Sphinx 及其autodoc模块以支持的格式（包括 HTML）构建文档。

请注意，图像必须采用builder输出支持的格式。