How can I display externally hosted images in my Sphinx (reStructured Text) document?

Question

Sphinx (http://sphinx-doc.org/index.html) uses restructured text to define the content. There are directives to display images from the local file system (using relative and absolute paths).

What I'd like to be able to do is declare an image using a URL and have it displayed in-line. The only way I can see this is to specify raw HTML, which seems a little crude. Is there an alternative - perhaps another "hidden" directive or plugin to support this?

The reason I need this is that I have a lot of images. If I store them on github I'll be forcing my users to download quite a large file to sync. I do appreciate I would lose the benefit of warnings from Sphinx for missing files.

Answer 1

To include an image from an URL you can put in your source.rst:

.. image:: http://my.url.com/my-picture1.png
    :alt: my-picture1

You may also put at the end of conf.py:

# A string of reStructuredText that will be included at the end of every source 
# file that is read.
rst_epilog = """

.. |pic2| image:: http://my.url.com/my-picture2.png
           :alt: my-picture2

"""

and in source.rst:

|pic2|

Finally, if you have a lot of images in the same place, you could do this: in conf.py put:

# The URL base of images
url_base = "http://my.url.com"

# A string of reStructuredText that will be included at the end of every source 
# file that is read.
rst_epilog = """

.. |pic3| image::{url_base}/my-picture3.png
           :alt: my-picture3
.. |pic4| image::{url_base}/my-picture4.png
           :alt: my-picture4

""".format(url_base=url_base)

and in source.rst:

|pic3|

|pic4|