How to do a link to a file in rst with sphinx?

python-sphinx restructuredtext
Ger picture Ger · Jan 15, 2013 · Viewed 30.2k times · Source

I am writing a documentation and I would like to include links to pdf files or zip archives. How can I achieve that using rst language and sphinx ?

If I do that 

here is a pdf file : `pdf <doc/mypdf.pdf>`_

It does not work because, during the compilation sphinx do not copy the contains of the doc directory (I use the makefile generated by sphinx-quickstart).

On the contrary, using the image directive :

.. image:: img/plop.png

sphinx does copy the plop.png image in build directory. How can I obtain the same behavior for pdf or zip archive ?

Answer

Ger picture Ger · Jan 15, 2013

A solution is to use the :download: “role” (detailed in the sphinx documentation on roles).

Here is a short example assuming you have a file mypdf.pdf in a directory doc. The directory doc and your rst file must be in the same directory:

here is a pdf file :download:`pdf <doc/mypdf.pdf>`

Note that you mustn't put a blank space between :download: and the path to the file.

Related questions

Adding a cross-reference to a subheading or anchor in another page

How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?

Read More
WARNING: document isn't included in any toctree for included file

I'm getting the warning: WARNING: document isn't included in any toctree for files that exist in the document because they've been explicitly included. So I have the index file: .. toctree:: :maxdepth: 2 pages/0010-foo pages/0020-bar In the file 0020-bar.rst, …

Read More
How can I link/reference another reST file in the documentation?

I have simply no idea on how can I link to another document in the reST file. I want to link a file named install.rst to my quickstart guide in a paragraph. I don't know how can I achieve …

Read More