From a5ef482ca898a1ce4fd4eaac03c64091c54d7f5d Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Tue, 9 Jun 2026 02:08:14 +0200
Subject: [PATCH] docs: offer a PDF download and link offline formats in the
 sidebar, fixes #9731

Enable the pdf output format on Read the Docs (the LaTeX build config
already existed in docs/conf.py) and add a "Downloads" line to the left
sidebar that links the offline formats (PDF, HTML zip, ePub). 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. The line is left-aligned with the boxes above and the
table of contents below, with separators above and below it.

Also drop the stale 'resources' entry from latex_appendices (the page was
removed in #2088); it broke the now-enabled PDF build with a doctree
KeyError.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .readthedocs.yaml              |  1 +
 docs/_templates/downloads.html | 27 +++++++++++++++++++++++++++
 docs/borg_theme/css/borg.css   | 14 ++++++++++++++
 docs/conf.py                   |  4 ++--
 4 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 docs/_templates/downloads.html

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 415f4b024..9d03a58f9 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -29,3 +29,4 @@ sphinx:
 
 formats:
     - htmlzip
+    - pdf
diff --git a/docs/_templates/downloads.html b/docs/_templates/downloads.html
new file mode 100644
index 000000000..ba4a968e1
--- /dev/null
+++ b/docs/_templates/downloads.html
@@ -0,0 +1,27 @@
+<p class="borg-downloads" id="borg-downloads" style="display:none;">Downloads: <span id="borg-downloads-list"></span></p>
+<script type="text/javascript">
+  // Populate offline download links (PDF, HTMLzip, ...) on a single line 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", epub: "ePub"};
+    var span = document.getElementById("borg-downloads-list");
+    if (!span) return;
+    var first = true;
+    Object.keys(downloads).forEach(function(fmt) {
+      var url = downloads[fmt];
+      if (!url) return;
+      if (!first) span.appendChild(document.createTextNode(" | "));
+      var a = document.createElement("a");
+      a.href = url;
+      a.textContent = labels[fmt] || fmt;
+      span.appendChild(a);
+      first = false;
+    });
+    if (!first) document.getElementById("borg-downloads").style.display = "";
+  }
+
+  document.addEventListener("readthedocs-addons-data-ready", function(event) {
+    borgInitDownloads(event.detail.data());
+  });
+</script>
diff --git a/docs/borg_theme/css/borg.css b/docs/borg_theme/css/borg.css
index 291c166c2..4d8bf330e 100644
--- a/docs/borg_theme/css/borg.css
+++ b/docs/borg_theme/css/borg.css
@@ -221,3 +221,17 @@ readthedocs-flyout {
 .sphinxsidebar > .sidebar-block:has(#main-search):after {
     margin: 7px 22px 0 22px;
 }
+/* Downloads line in the sidebar: a single line, left-aligned with the boxes
+   above it and the table of contents below it. */
+.borg-downloads {
+    padding: 0 22px;
+    margin: 7px 0 7px 0;
+    font-size: 14px;
+    color: #000;
+}
+.borg-downloads:after {
+    content: '';
+    display: block;
+    border-top: 1px solid #ccc;
+    margin: 7px 0 0 0;
+}
diff --git a/docs/conf.py b/docs/conf.py
index d64ee038e..75b956efa 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -156,7 +156,7 @@ html_use_smartypants = True
 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"]}
+html_sidebars = {"**": ["logo-text.html", "versionselector.html", "searchbox.html", "downloads.html", "globaltoc.html"]}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -218,7 +218,7 @@ latex_show_urls = "footnote"
 # latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
-latex_appendices = ["support", "resources", "changes", "authors"]
+latex_appendices = ["support", "changes", "authors"]
 
 # If false, no module index is generated.
 # latex_domain_indices = True