通过 CMake 在 Sphinx 文档中使用生成的图像

【问题标题】：Use generated images in a Sphinx document with CMake通过 CMake 在 Sphinx 文档中使用生成的图像
【发布时间】：2022-01-18 14:48:55
【问题描述】：

如何在 Sphinx 源目录之外自动生成的 Sphinx .rst 文件中包含图像？

我使用 CMake 构建了一个 Sphinx 项目。 Sphinx 源文件之一包含由 CMake 项目中的单独目标生成的 PDF 图像。据我了解，不应从 CMake 源代码树中的 CMake 构建过程生成输出。（我认为这可以通过不同的 CMake 构建配置生成不同的输出来证明）。因此，Sphinx 构建的输入不能在 Sphinx 源树中，并且在编写 Sphinx 代码时，要包含在 Sphinx 文档中的图像的相对路径是未知的。

我该如何解决这个问题？

【问题讨论】：

标签： cmake python-sphinx

【解决方案1】：

这是一个解决方案的草图（太大，无法评论）：

您可以使用环境变量集从 CMake 调用 Sphinx，该环境变量集指向存储生成的图像的构建（子）目录。用add_custom_command 和${CMAKE_COMMAND} -E env ... 传递这个
您的 Sphinx 配置可以读取该环境变量 (``) 并将结果添加到 html_static_path:

import os

# ...

html_static_path = [
   # ...
   os.getenv('BUILD_DIR'),
]

然后确保您有一个自定义目标（称为generate_doc_images）来驱动生成图像的自定义命令。使用 add_dependencies 确保图像生成器在 Sphinx 之前运行。

如果您提供的 MRE 几乎可以让您顺利到达那里，我可以帮助您正确连接。

【讨论】：