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>`_. 

Scale

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>`_. 

Scale

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 – Indohittite

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! – Asclepius

I see. So just a note here for these trying :download: e.g. from #14346422 . 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. – Rafaelita

Answer 2

@silverninja-msft wants a solution using restructuredText, however if embeddeding Markdown using MySt parser is possible:

Solution using MySt parser and Markdown

Using customized external URL resolution we can create a customized URL in conf.py and copy the file to be linked to the root of the directory using html_extra_path. Assuming that the file _extra/file.html exists, we can use the following lines in conf.py:

# These files provided here are simply copied to the root.
html_extra_path = ["_extra"]

myst_url_schemes = {
  "local": "./{{path}}#{{fragment}}",
}

Then we can link to fragments of the HTML file as follows:

[Local link](local:file.html#section1)

<local:file.html#section1>

Further use of customized external URLs

I use customized external URLs also to link to directories on the source repository and to shorten the links to the often used documents as follows:

myst_url_schemes = {
  "http": None,  # Otherwise this scheme is not treated as external links
  "https": None,
  "isa": "./unpriv-isa-asciidoc.html#{{fragment}}",
  "repo": html_theme_options["repository_url"]
  + "/-/tree/main/{{path}}#{{fragment}}",

Comparison with silverninja-msft's solution

@silverninja-msft's solution has the following drawbacks on Sphinx 7.2.6

1. It only works with a PDF file, but not with an HTML file. Linked HTML file is not shown inline.
2. HTML fragments, e.g., file.pdf#section1, do not work.

Slavery