Merge pull request #9739 from ThomasWaldmann/pdf-docs-master

docs: offer a PDF download and link offline formats in the sidebar

.readthedocs.yaml

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

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>

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;
+}

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