Search code examples
imagepython-sphinxsubstitutionrestructuredtext

Point sphinx to images in build directory


I have a C++ project that I'm documenting with Sphinx. To keep the source directory clean, it uses an out-of-source build. I have a tutorial program that gets built as part of the project and generates an image in the build directory, not the project source directory. How can I reference the image in documentation files in the source directory when I have no control over the relative location of the source and build directories of the project?

I've tried using an rst_epilog in conf.py like so:

rst_epilog = """
.. |builddir| replace:: %s
""" % project_build_dir

and then refer to the image like so:

.. figure:: |builddir|/generated.png

but end up with errors like "WARNING: image file not readable: |builddir|/generated.png".


Solution

  • It looks like this is answered in the negative by this question: reStructured Text (Sphinx) : substitution in a file name? . Substitutions cannot be used in image directives to modify the filename and no alternative was offered other than to write a new extension or manually generate an image substitution for every image.