From 1bf806b2f28f1454d9f1f7e9cff749f166282711 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Tue, 9 Jun 2026 01:05:46 +0200
Subject: [PATCH] docs: offer PDF download and link offline formats in sidebar,
 fixes #9731

Enable the pdf format on Read the Docs (the LaTeX build config already
existed in conf.py) and add a "Download docs" section to the sidebar that
links the offline formats (PDF, HTML zip, ...). The links are populated
from the Read the Docs addons data, reusing the same mechanism as the
version selector, so they are version-correct and hidden when unavailable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .readthedocs.yaml              |  1 +
 docs/_templates/downloads.html | 31 +++++++++++++++++++++++++++++++
 docs/conf.py                   |  2 +-
 3 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 docs/_templates/downloads.html

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 784ad2981..809723f67 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -31,3 +31,4 @@ sphinx:
 
 formats:
     - htmlzip
+    - pdf
diff --git a/docs/_templates/downloads.html b/docs/_templates/downloads.html
new file mode 100644
index 000000000..d89418e53
--- /dev/null
+++ b/docs/_templates/downloads.html
@@ -0,0 +1,31 @@
+<div class="borg-downloads" id="borg-downloads" style="display:none;">
+  <p class="caption"><span class="caption-text">Download docs</span></p>
+  <ul id="borg-downloads-list"></ul>
+</div>
+<script type="text/javascript">
+  // Populate offline download links (PDF, HTMLzip, ...) using ReadTheDocs data if available.
+  function borgInitDownloads(data) {
+    var downloads = data && data.versions && data.versions.current && data.versions.current.downloads;
+    if (!downloads) return;
+    var labels = {pdf: "PDF", htmlzip: "HTML (zip)", epub: "ePub"};
+    var list = document.getElementById("borg-downloads-list");
+    if (!list) return;
+    var count = 0;
+    Object.keys(downloads).forEach(function(fmt) {
+      var url = downloads[fmt];
+      if (!url) return;
+      var li = document.createElement("li");
+      var a = document.createElement("a");
+      a.href = url;
+      a.textContent = labels[fmt] || fmt;
+      li.appendChild(a);
+      list.appendChild(li);
+      count++;
+    });
+    if (count) document.getElementById("borg-downloads").style.display = "";
+  }
+
+  document.addEventListener("readthedocs-addons-data-ready", function(event) {
+    borgInitDownloads(event.detail.data());
+  });
+</script>
diff --git a/docs/conf.py b/docs/conf.py
index fda14f2ed..459364ad7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -161,7 +161,7 @@ smartquotes_action = 'qe'  # no D in there means "do not transform -- and ---"
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
-    '**': ['logo-text.html', "versionselector.html", 'searchbox.html', 'globaltoc.html'],
+    '**': ['logo-text.html', "versionselector.html", 'searchbox.html', 'downloads.html', 'globaltoc.html'],
 }
 
 # Additional templates that should be rendered to pages, maps page names to