14

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>`_.
Community
  • 1
  • 1
SliverNinja - MSFT
  • 31,051
  • 11
  • 110
  • 173

1 Answers1

15

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>`_.
SliverNinja - MSFT
  • 31,051
  • 11
  • 110
  • 173
  • 2
    Thank you for this answer. I now put PDF files into an `_assets` directory. I've set `html_static_path = ['_static', '_assets']`, so now references/links to PDFs can be things like `.. _how to write mathematics: ../_static/how-to-write-mathematics-halmos.pdf` – Doug Cuthbertson Apr 14 '18 at 10:58
  • Been looking for this answer for several hours, after trying all kind of options w/o success: ":file", ":download:"," .. literalinclude:: ", ":ref:", ".. image::". None of them worked, and its hard to believe not many people are looking for this. I thank you very much for this solution! – Kiteloopdesign Mar 25 '21 at 11:46