Specifying an online image in Sphinx (restructuredtext) format

Question

Any ideas on how I can refer to an online image while documenting with Sphinx?

This does NOT work:

.. image:: http://www.mysite.com/images/someimage.png

Gives me:

/home/user/proj/2010/11/08/the_forever_war.rst:11: WARNING: nonlocal image URI found: http://www.mysite.com/images/someimage.png

Thanks...

Answer 1

As of sphinx 1.4, you can "monkey patch" sphinx from your docs/conf.py file like so:

import sphinx.environment
from docutils.utils import get_source_line

def _warn_node(self, msg, node, **kwargs):
    if not msg.startswith('nonlocal image URI found:'):
        self._warnfunc(msg, '%s:%s' % get_source_line(node), **kwargs)

sphinx.environment.BuildEnvironment.warn_node = _warn_node

A previous version of this answer provided a patch that is incompatible with the latest sphinx 1.4 release[1]. Furthermore, the next release of sphinx should support this configuration option[2]:

suppress_warnings = ['image.nonlocal_uri']

This will exclude any warnings of 'nonlocal image URI found'.

I found this necessary because I want the sphinx-build -W to emit "warnings as errors" as part of my test & build infrastructure, to ensure that there are no mistakes in the documentation -- I know very well that I'm using nonlocal image URI's and I'm OK with that, but I don't want to ignore the other warnings.

[1] https://github.com/sphinx-doc/sphinx/issues/2429#issuecomment-210255983

[2] https://github.com/sphinx-doc/sphinx/issues/2466

Answer 2

I use raw html code for this, e.g.:

.. raw:: html

   <p style="height:22px">
     <a href="https://travis-ci.org/aio-libs/aiozmq" >
       <img src="https://travis-ci.org/aio-libs/aiozmq.svg?branch=master"/>
     </a>
   </p>