How to serve static objects without image from readthedocs site?

Question

I have an assets folder in my docs folder that contains files with samples and samples related to my project documentation.

Images fit correctly into my documentation, but any links to sample input files (static files that are inputs to my project binaries) 404.

For example, in my documentation there may be text formatted in the format:

 Open this `example`_ input file to see the following result: .. image:: ../../assets/foo.png .. _example: ../../assets/bar.tgz 

The image foo.png displayed correctly. The tarball link associated with _example leads to 404 pages.

Both files foo.png and bar.tgz are in the main github distribution and are on the specified path.

I tried make html by pushing the changes through git and redoing the documents.

How can I fix this so that the documentation works with the assets included in the github distribution? (I suggest that I should avoid referencing the github source address due to versions.)

Answer 1

Reading Documents does not serve arbitrary files from your repository; it serves only the results of the Sphinx build process. Therefore, instead of binding to files, as in your example, use :download: The role tells Sphinx to include additional files in the directory in the output of the assembly.

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 is displayed, not the HTML output.