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.

Answer 1

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.