Sphinx: Linking to Embedded Binary Files (PDFs)

Question

I'm using sphinx and RST to generate some tech documentation as HTML and having issues getting a local PDF reference to work as a hyperlink. I've seen people use :download: to link to local PDFs, but I'm embedding the PDFs inside a /docs directory for reference. I don't like :download: because it doesn't display the PDF inline in the browser which requires an extra step on the users' behalf for consumption.

sphinx-build -b html does not copy any files unless they are specified in config.py hook html_static_path or html_extra_path - and even then they are dropped to the root directory or _static folders.

Is there a suggested approach for embedding linked binary files within sphinx or is this a poor practice? Often times the links are to slide decks or design diagrams that are not hosted anywhere else.

Sample RST for linked PDF

.. important:: View the agile course on scrum basics

    - View `these slides to dive deeper into Agile Basics <docs/agile-101.pdf>`_. 

Answer 1

The solution I came up with was to just add the PDFs to html_static_path and reference the _static output path in the link instead of the docs path where it lives in the source. Now PDFs open up in the browser instead of having to download them to view.

Would be great if there was an sphinx extension / directive to handle this (:download-inline:).

conf.py

html_static_path = ['_static', 'agile-101/docs']

agile-101.rst

.. important:: View the agile course on scrum basics

- View `these slides to dive deeper into Agile Basics <../_static/agile-101.pdf>`_.