如何避免在 Sphinx 中多次处理 plot 指令？

Question

我正在使用 Sphinx 记录一个包含多个绘图示例的小型代码项目。使用 Sphinx/matplotlib 绘图指令，我想在文档中多次引用这些示例，通常是：

• 在 API 中（通过在文档字符串中使用 plot 指令），
• 在所有示例列表中（如 matplotlib 文档中），
• 可能也在用户文档中。

我的所有示例都位于一个目录中，因此我使用以下方式引用它们：

.. plot:: ../examples/demo.py

但这会导致 Sphinx 多次处理 demo.py，生成多个输出图像 demo.png、demo1.png 等。这会使构建目录变得杂乱无章，并使构建文档变得不必要地缓慢。

如何确保每个示例只处理一次？

Answer 1

也许这并不令人满意，但该指令可能不适用于您相当复杂的用例。您是否考虑过提前创建绘图图形，然后将它们简单地包含为图像（然后您当然可以重复使用）？

您可以将这种方法自动化到任何程度，因此您无需手动修改文件路径。