在python文档中嵌入图像

Question

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

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

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

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

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

Answer 1

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

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

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

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