Sphinx - reference to an image from different locations

Question

I am using Python Sphinx (via ReadTheDocs).

I have a repository which contains a few sub-modules, and I'm trying to create a unified documentation, but still keep the the docs assets in each module separately.

My folder hierarchy is:

MyProject
  docs
    index.rst
    module_1_link.rst
      _static
        <more irrelevant assets...>               
  module_1
    docs
      README.rst
      _static
        myimage.png

The index.rst file looks like this:

.. toctree::
    :caption: Module1
    module_1_link

The file module_1_link.rst just contains a link to the README file of module 1:

.. include:: ../module1/docs/README.rst

And the README.rst of module 1 references the image:

.. image:: _static/myimage.jpg

When I look at the README file of module 1 (inside GitHub) - myimage.png is shown perfectly.

But, when I run the documentation via sphinx I get:

 WARNING: image file not readable: _static/myimage.jpg

I can't find a way to reference the same image from both the README file and the index file rendered by sphinx and see it in both places.

score 8 · Answer 1 · answered Sep 02 '18 at 21:34

8

Change the reference to the image in README.rst to be relative to the documentation root.

.. image:: /module1/docs/_static/myimage.jpg

See also Sphinx documentation on paths to 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.

answered Sep 02 '18 at 21:34

Steve Piercy

13,693
1
44
57

Thanks for the comment @Steve! So this definitly lets me see the image correctly in the module1 README.rst, but again, when the ReadTheDocs runs on the entire project I get "WARNING: image file not readable module1/docs/_static/myimage.jpg" – ShaharA Sep 03 '18 at 06:37
It sounds like part of your project was not installed by RTD. Got link to the build log? – Steve Piercy Sep 03 '18 at 10:38
Yes - https://readthedocs.org/projects/unicorn-project/builds/7726818/ Thanks you! – ShaharA Sep 03 '18 at 10:50
Try making your include directives root-relative as well. – Steve Piercy Sep 03 '18 at 10:59
Thanks for all the help @Steve. I tried your last comment. still no luck but I'm trying more stuff – ShaharA Sep 04 '18 at 12:24

Sphinx - reference to an image from different locations

1 Answers1