What's the best way to include a PDF in my Sphinx documentation?

Question

I have a PDF that has some in depth explanation for an example in the Sphinx documentation for a package I have. Is there a way to easily include the PDF in my project (and have it copy over when I build the docs)? I tried linking to it with :doc: but this did not copy it over.

Answer 1

Use the :download: text role to bring in an arbitrary additional file. So in your case you might do something like this:

For an in-depth explanation, please see :download:`A Detailed Example <some_extra_file.pdf>`.