Search code examples
imagepython-sphinxrestructuredtext

docs: missing images when using include directives (rst, sphinx)

I am generating docs using rst/sphinx and am having a problem with images in referenced files.

The include directive works well to bring in rst files, but I am not getting the images that are themselves referenced from the included files.

My structure is like this:

   /documentation
        /master_doc
            /source
                pointer_file.rst  
                    and this file calls file.rst:
                    include:: ../../doc_a/source/file.rst
        /documents
             /doc_a
                  /source
                       /images
                            picture.jpg
                       file.rst
                             includes a figure ref:
                             .. figure:: images/picture.jpg

When I build from doc_a directory, I get text + image. All good. But when I build from the master_doc directory, where the include directive comes in, I get only the text and the image is missing in the build.

How can I fix this? I don't want to have to duplicate all my images in both directories, which is the only thing that seems to work at present.

***EDIT: Added detail to project structure above since suggested fix below does not yet work.

I tried all of the following in response to the suggestion in the first comment, and none of it worked:

.. figure:: /documentation/documents/doc_a/source/images/picture.jpg

and 

.. figure:: /documents/doc_a/source/images/picture.jpg

and 

.. figure:: /doc_a/source/images/picture.jpg

Any other ideas?

Solution

  • I solved this problem. Thanks to Steve Piercy for asking helpful questions. I had to do 2 things:

    1. move all images to a shared_images folder, at the same relative distance from all doc projects, and

    2. re-organize my project folders to make them siblings.

    Now my image refs are all to: ../../../shared_images/. It works!