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

Question

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 ?

Quiddity

try the :download: role -- see #2922224 – Pernell

Answer 1

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.

Quiddity

Alternatively, you can put your file in the _static folder (or whatever you configured that to be), and reference it directly from there. – Wheeler

Link is outdated unfortunately. I did not find the updated version. – Shortie

@Mayou36: link to the :download: role documention is now fixed. – Festus

Just a small note for these trying to use :download: with no success. Files you want to be accessible by :download:`name <_static/file.pdf>` need to be present in docs/source/_static/ when you are building HTML. You can not just put them to docs/build/html/_static/ afterwards. – Euhemerism

Answer 2

The image directive only works for HTML with PDF files.

.. image:: doc/mypdf.pdf

DO NOT use it, because it is misleading. Thanks to comment of G. Milde.

Extensity

This will only show a link to the PDF-file, not display the file itself (which is something I am struggling with at the moment). – Tithing

@Tithing OP asked for a link. Have a try with .. figure:: doc/mypdf.pdf to show the PDF. – Extensity

It works for HTML, as the PDF image format is not supported by most HTML browsers. Abusing the "image" directive for download links is missleading and error prone, though. Exporting to LaTeX would include the PDF as image. – Allochthonous