CODEWITHSUNDEEP
pythongithubrestructuredtextpypi
thebjorn
thebjorn

Reputation: 27321

How do you link to images from your docs folder in your README.rst?

I'm struggling to find a way to use images in my README.rst that will show up both on github and PyPI.

Currently I'm using the following markup:

.. image:: https://github.com/thebjorn/pydeps/blob/master/docs/_static/pydeps.svg

which looks great on github (https://github.com/thebjorn/pydeps), but show up as broken links on PyPI (https://pypi.org/project/pydeps/1.6.0/).

Is this possible, or do I need to host these images somewhere else?

Upvotes: 4

Views: 1866

Answers (1)

hoefling
hoefling

Reputation: 66271

You need to use raw.githubusercontent.com instead of github.com:

.. image:: https://github.com/thebjorn/pydeps/blob/master/docs/_static/pydeps-pylib.svg

will render correctly only on Github itself, while

.. image:: https://raw.githubusercontent.com/thebjorn/pydeps/master/docs/_static/pydeps-pylib.svg?sanitize=true

will render on any website.

First attempt (broken & removed)

Second attempt:

  1. replaces the URLs correctly (also removing the blob part in paths - my bad!),
  2. appends ?sanitize=true to each URL being replaced.
$ sed -i '' 's,.. image:: https://github.com/\(.*\)/blob/\(.*\).svg,.. image:: https://raw.githubusercontent.com/\1/\2.svg?sanitize=true,g' README.rst

Testing it on Github and on TestPyPI, both looking good.

Alternative: Using RawGit

Another possibility would be using RawGit, although the downside is this being a third-party service, so when it's down, the images are not rendered, although available. Nevertheless, for completeness:

$ sed -i '' 's,.. image:: https://github.com/\(.*\)/blob/\(.*\)$,.. image:: https://cdn.rawgit.com/\1/\2,g' README.rst

Upvotes: 5

Related Questions