How to avoid multiple processing of the plot directive in Sphinx?

Question

I am using Sphinx to document a small code project with several plotting examples. Using the Sphinx/matplotlib plot directive, I would like to refer to these examples multiple times in the docs, typically:

• in the API (through using the plot directive in docstrings),
• in a list of all examples (as in the matplotlib docs),
• perhaps in the user documentation, too.

All my examples are located in one directory, thus I refer to them using:

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

But this results in Sphinx processing demo.py multiple times, producing several output images demo.png, demo1.png, etc. This is cluttering the build directory and makes building the docs unnecessarily slow.

How can I ensure that each example is processed only once?

Answer 1

Maybe this is not satisfactory, but that directive may not be made for your rather complex use case. Did you consider creating the plot graphics in advance, and then simply include them as images (which you then can of course re-use)?

You can automate this approach up to any degree, so that you do not need to manually fiddle with file paths.