Downloadable Files in Documentation#

This page describes how to provide downloadable files (HTML visualizations, JSON drawings, etc.) alongside embedded content in the Sphinx documentation.

This is useful when an interactive HTML visualization is embedded via <iframe> — the reader can also download the .html file to open it locally in a browser, zoom in, or share it.

Overview#

Three things must be in place:

A data/ directory at the project root containing the files to offer for download.
A symlink doc/_data pointing to that data/ directory, making it visible to Sphinx.
The :download: RST role in .rst source files to generate the download link.

No Sphinx extension or conf.py change is needed. The :download: role is built into Sphinx.

For HTML visualization files that live in doc/source/_static/html/, no symlink is needed — they are already inside the Sphinx source tree. Use a relative path directly.

Step 1: Create the symlink (one-time setup)#

If not already done, create a symlink from doc/ to the project data/ directory:

cd doc/
ln -s ../data _data

This makes any file at data/json/my_drawing.json reachable from Sphinx as /_data/json/my_drawing.json.

Commit the symlink:

git add doc/_data
git commit -m "Add symlink for downloadable data files"

Step 2: Add a download link in RST#

Use the :download: role:

:download:`display text <path_to_file>`

Path conventions:

Style	Example	When to use
Absolute (leading `/`)	`/_data/json/my_drawing.json`	From any RST file at any depth. Preferred.
Relative	`../_static/html/my_visu.html`	For files inside `doc/source/` (HTML visualizations).

Step 3: Combine iframe + download link#

The typical pattern for an interactive visualization with a download link:

*Source: GICLEUR, Sheet 0 — Dimensions highlighted in red*

.. raw:: html

   <iframe src="../_static/html/plot_data_view_examples/example_sheet_dimensions.html"
           width="100%" height="600px" frameborder="0"></iframe>

.. tip::

   :download:`Download this visualization <../_static/html/plot_data_view_examples/example_sheet_dimensions.html>`

This renders the interactive visualization inline, with a download link below it.

For data files (JSON drawings)#

.. tip::

   **Drawing file:** :download:`GICLEUR.json </_data/json/RP6541D072_GICLEUR A00.json>`

Checklist#

Place the file in the right location (data/ for data files, doc/source/_static/html/ for visualizations)
Verify the doc/_data symlink exists (for data files only)
Add :download: role in the RST page
Optionally wrap in .. tip:: for visibility
Build docs (make html) and verify the download link works