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 ?

try the `:download:` role -- see http://stackoverflow.com/questions/2921724/include-a-text-file-as-is-in-python-sphinx-docs/ — Bonlenfum, Jan 15 '13 at 20:31

score 78 · Answer 1 · edited Dec 02 '19 at 11:34

78

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.

edited Dec 02 '19 at 11:34

Pierre H.

388
1
11

answered Jan 15 '13 at 20:32

Ger

9,076
10
37
48

1

Alternatively, you can put your file in the `_static` folder (or whatever you configured that to be), and reference it directly from there. – Mad Physicist Jul 11 '18 at 19:05
1

Link is outdated unfortunately. I did not find the updated version. – Mayou36 Jul 30 '19 at 15:27
@Mayou36: link to the :download: role documention is now fixed. – Pierre H. Dec 02 '19 at 10:38

score -1 · Answer 2 · answered Aug 24 '18 at 15:11

-1

The image directive also works for PDF files.

.. image:: doc/mypdf.pdf

answered Aug 24 '18 at 15:11

Henrik

2,771
1
23
33

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). – 1313e Dec 06 '18 at 00:45
@1313e OP asked for a link. Have a try with `.. figure:: doc/mypdf.pdf` to show the PDF. – Henrik Dec 10 '18 at 12:42

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

2 Answers2

Linked