4

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.)

barryhunter
  • 20,886
  • 3
  • 30
  • 43
Alex Reynolds
  • 95,983
  • 54
  • 240
  • 345

1 Answers1

4

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.

RayLuo
  • 17,257
  • 6
  • 88
  • 73
ddbeck
  • 3,855
  • 2
  • 28
  • 22
  • 1
    @ddbeck Is there a similar way to do this when using MarkDown instead of ReStructuredText? – Alasdair Sep 09 '15 at 17:13
  • 1
    @Alasdair do you mean with the recommonmark library? I haven't actually tried it yet myself, but it's my understanding that it doesn't support many of Sphinx's features. To work around it, you could use the Sphinx [`html_extra_path`](http://sphinx-doc.org/latest/config.html#confval-html_extra_path) setting in your `conf.py` file to add arbitrary files to your HTML output. – ddbeck Sep 15 '15 at 08:05
  • thanks will give it a shot. Currently wrestling with selfhosting readthedocs for production (dev environment works fine). Will come back to this. – Alasdair Sep 15 '15 at 11:45