在Python文档中嵌入图片

Question

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

在这份文档中，允许嵌入图片非常关键。同时，我不想创建一个单独的文件。换句话说：*.py文件应该包含脚本和文档（其中包含嵌入的图片）。

当然，以后会使用工具处理*.py文件，生成Markdown或HTML报告。

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

有人知道如何使用这些工具（或其他工具）实现类似的功能吗？

- guilhermecgs

---

"嵌入"是什么意思？在Base64中编码图像？ - mzjn

只需提供图像文件的链接。当在浏览器中打开(html, md)文件时，浏览器应该呈现图像。 - guilhermecgs

那么，“我想不创建单独的文件”是什么意思？ - mzjn

抱歉造成困惑：我不熟悉所有的文档工具。在我看来，如果我有一个“source.py”，一个常见的用例是手动创建一个包含所有文档的“source.md”文件。在这种情况下，将会有两个文件。我想要的是“source.py”同时包含代码、文档、图像链接等。运行外部工具命令后，“source.md（html）”将被生成。 - guilhermecgs

你可以在Python模块中添加文档字符串作为文档。使用Sphinx，这些文档字符串可以被提取并包含在HTML输出中。请参阅http://www.sphinx-doc.org/en/stable/ext/autodoc.html。 - mzjn

Answer 1

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

要使用 Sphinx 构建文档，您需要一组 reStructuredText 文件，从中构建文档。您可以使用 Sphinx quick-start 生成 .rst 源文件。

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

请注意，图片必须是生成器输出支持的格式。

- Steve Piercy