CODEWITHSUNDEEP
imagepython-sphinxrestructuredtext
Fiona Hanington
Fiona Hanington

Reputation: 71

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?

Upvotes: 5

Views: 3966

Answers (2)

Fiona Hanington
Fiona Hanington

Reputation: 71

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!

Upvotes: 2

Steve Piercy
Steve Piercy

Reputation: 15055

Try changing your image file path from relative to absolute.

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

From reStructuredText Primer, Images:

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.

Upvotes: 5

Related Questions