How to serve static non-image asset from a readthedocs site?

Question

I have an assets folder in my docs folder that contains image and sample input files associated with my project documentation.

The images embed correctly in my documentation, but any links to sample input files (static files that are inputs to my project binaries) are 404ed.

For example, here could be the reSt-formatted text in my documentation:

Open this `example`_ input file to see the following result:

.. image:: ../../assets/foo.png

.. _example: ../../assets/bar.tgz

The image foo.png is rendered correctly. The link to the tarball linked from _example leads to a 404 page.

Both files foo.png and bar.tgz are in the master github distribution and are at the path specified.

I have tried make html, pushing changes via git and rebuilding documents.

How could I go about fixing this, so that the documentation works with assets that are part of the github distribution? (I'm guessing that I should avoid linking to a raw github address, because of versioning.)

Answer 1

Read the Docs doesn't serve arbitrary files from your repository; it only serves the results of the Sphinx build process. So instead of linking to files as in your example, use the :download: role. The role tells Sphinx to include the extra files in a directory in the build output.

So, your example modified to use :download: might look something like this:

Open this :download:`example <../path/to/bar.tgz>` input file to see the following result:

Note that the file path is relative to the reStructuredText file where the role appears, not the HTML output.