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 <[email protected]>

.readthedocs.yaml

@@ -31,3 +31,4 @@ sphinx:
 
 formats:
     - htmlzip
+    - pdf

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>

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