Changes for RTD

.github/workflows/sphinx.yml

@@ -13,7 +13,7 @@ jobs:
         run: make doc
 
       - name: Print warnings
-        run: if [ -s .sphinx/warnings.txt ]; then cat .sphinx/warnings.txt; exit 1; fi
+        run: if [ -s doc/.sphinx/warnings.txt ]; then cat doc/.sphinx/warnings.txt; exit 1; fi
 
       - name: Upload artifacts
         if: always()

.gitignore

@@ -18,12 +18,12 @@ test/macaroon-identity/macaroon-identity
 
 # Sphinx
 doc/html/
-.sphinx/deps/
-.sphinx/themes/
-.sphinx/venv/
-.sphinx/warnings.txt
-.sphinx/_static/swagger-ui
-.sphinx/_static/download
+doc/.sphinx/deps/
+doc/.sphinx/themes/
+doc/.sphinx/venv/
+doc/.sphinx/warnings.txt
+doc/.sphinx/_static/swagger-ui
+doc/.sphinx/_static/download
 
 # For Atom ctags
 .tags

Makefile

@@ -9,7 +9,7 @@ HASH := \#
 TAG_SQLITE3=$(shell printf "$(HASH)include <dqlite.h>\nvoid main(){dqlite_node_id n = 1;}" | $(CC) ${CGO_CFLAGS} -o /dev/null -xc - >/dev/null 2>&1 && echo "libsqlite3")
 GOPATH ?= $(shell go env GOPATH)
 CGO_LDFLAGS_ALLOW ?= (-Wl,-wrap,pthread_create)|(-Wl,-z,now)
-SPHINXENV=.sphinx/venv/bin/activate
+SPHINXENV=doc/.sphinx/venv/bin/activate
 
 ifneq "$(wildcard vendor)" ""
 	RAFT_PATH=$(CURDIR)/vendor/raft
@@ -120,20 +120,15 @@ endif
 .PHONY: doc
 doc:
 	@echo "Setting up documentation build environment"
-	python3 -m venv .sphinx/venv
-	. $(SPHINXENV) ; pip install --upgrade -r .sphinx/requirements.txt
-	mkdir -p .sphinx/deps/ .sphinx/themes/
-	git -C .sphinx/deps/swagger-ui pull || git clone --depth 1 https://github.com/swagger-api/swagger-ui.git .sphinx/deps/swagger-ui
-	mkdir -p .sphinx/_static/swagger-ui
-	ln -sf ../../deps/swagger-ui/dist/swagger-ui-bundle.js ../../deps/swagger-ui/dist/swagger-ui-standalone-preset.js ../../deps/swagger-ui/dist/swagger-ui.css .sphinx/_static/swagger-ui/
-	wget -N -P .sphinx/_static/download https://linuxcontainers.org/static/img/favicon.ico https://linuxcontainers.org/static/img/containers.png https://linuxcontainers.org/static/img/containers.small.png
+	python3 -m venv doc/.sphinx/venv
+	. $(SPHINXENV) ; pip install --upgrade -r doc/.sphinx/requirements.txt
 	rm -Rf doc/html
 	make doc-incremental
 
 .PHONY: doc-incremental
 doc-incremental:
 	@echo "Build the documentation"
-	. $(SPHINXENV) ; sphinx-build -c .sphinx/ -b dirhtml doc/ doc/html/ -w .sphinx/warnings.txt
+	. $(SPHINXENV) ; sphinx-build -c doc/ -b dirhtml doc/ doc/html/ -w doc/.sphinx/warnings.txt
 
 .PHONY: doc-serve
 doc-serve:

doc/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: doc/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: doc/.sphinx/requirements.txt

.sphinx/_static/custom.css → doc/.sphinx/_static/custom.css

@@ -153,3 +153,22 @@ button.version_select {
 .available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
 
 .show {display:block;}
+
+/** Fix the styling of the version box for readthedocs **/
+
+#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version  {
+    background: var(--color-sidebar-item-background--hover);
+}
+
+.rst-versions .rst-other-versions dd a {
+    color: var(--color-link);
+}
+
+#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
+    color: var(--color-sidebar-link-text);
+}
+
+.rst-versions .rst-current-version {
+    color: var(--color-version-popup);
+    font-weight: bolder;
+}

.sphinx/_templates/sidebar/variant-selector.html → doc/.sphinx/_templates/sidebar/variant-selector.html

@@ -1,4 +1,9 @@
+{% if ON_RTD %}
+  {% extends "furo/sidebar/variant-selector.html" %}
+  {{ super() }}
+{% else %}
 <div class="version_dropdown">
   Doc version: <button onclick="dropdown()" class="version_select" id="current"></button>
   <div id="all-versions" class="available_versions"></div>
 </div>
+{% endif %}

.sphinx/requirements.txt → doc/.sphinx/requirements.txt

@@ -32,3 +32,5 @@ sphinx-reredirects
 linkify-it-py
 furo
 sphinxext-opengraph>=0.6.1
+gitpython
+wget

.sphinx/conf.py → doc/conf.py

@@ -1,6 +1,31 @@
 import datetime
 import os
 import yaml
+from git import Repo
+import wget
+
+# Download and link swagger-ui files
+if not os.path.isdir('.sphinx/deps/swagger-ui'):
+    Repo.clone_from('https://github.com/swagger-api/swagger-ui', '.sphinx/deps/swagger-ui', depth=1)
+
+os.makedirs('.sphinx/_static/swagger-ui/', exist_ok=True)
+
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-bundle.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-bundle.js', '.sphinx/_static/swagger-ui/swagger-ui-bundle.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-standalone-preset.js', '.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui.css'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui.css', '.sphinx/_static/swagger-ui/swagger-ui.css')
+
+# Download and link images
+os.makedirs('.sphinx/_static/download/', exist_ok=True)
+
+if not os.path.isfile('.sphinx/_static/download/favicon.ico'):
+    wget.download("https://linuxcontainers.org/static/img/favicon.ico", ".sphinx/_static/download/favicon.ico")
+if not os.path.isfile('.sphinx/_static/download/containers.png'):
+    wget.download("https://linuxcontainers.org/static/img/containers.png", ".sphinx/_static/download/containers.png")
+if not os.path.isfile('doc/.sphinx/_static/download/containers.small.png'):
+    wget.download("https://linuxcontainers.org/static/img/containers.small.png", ".sphinx/_static/download/containers.small.png")
 
 # Project config.
 project = "LXD"
@@ -27,21 +52,21 @@
 myst_linkify_fuzzy_links=False
 myst_heading_anchors = 7
 
-if os.path.exists("../doc/substitutions.yaml"):
-    with open("../doc/substitutions.yaml", "r") as fd:
+if os.path.exists("./substitutions.yaml"):
+    with open("./substitutions.yaml", "r") as fd:
         myst_substitutions = yaml.safe_load(fd.read())
 
 # Setup theme.
-templates_path = ["_templates"]
+templates_path = [".sphinx/_templates"]
 
 html_theme = "furo"
 html_show_sphinx = False
 html_last_updated_fmt = ""
-html_favicon = "_static/download/favicon.ico"
-html_static_path = ['_static']
+html_favicon = ".sphinx/_static/download/favicon.ico"
+html_static_path = ['.sphinx/_static']
 html_css_files = ['custom.css']
 html_js_files = ['header-nav.js','version-switcher.js']
-html_extra_path = ['_extra']
+html_extra_path = ['.sphinx/_extra']
 
 html_theme_options = {
     "sidebar_hide_name": True,
@@ -72,6 +97,7 @@
         "color-highlighted-background": "#EbEbEb",
         "color-link-underline": "var(--color-background-primary)",
         "color-link-underline--hover": "var(--color-background-primary)",
+        "color-version-popup": "#772953"
     },
     "dark_css_variables": {
         "color-foreground-secondary": "var(--color-foreground-primary)",
@@ -95,6 +121,7 @@
         "color-highlighted-background": "#666",
         "color-link-underline": "var(--color-background-primary)",
         "color-link-underline--hover": "var(--color-background-primary)",
+        "color-version-popup": "#F29879"
     },
 }
 
@@ -105,21 +132,27 @@
     "github_filetype": "md"
 }
 
-html_sidebars = {
-    "**": [
-        "sidebar/variant-selector.html",
-        "sidebar/search.html",
-        "sidebar/scroll-start.html",
-        "sidebar/navigation.html",
-        "sidebar/scroll-end.html",
-    ]
-}
+# Pass a variable to the template files that informs if we're on
+# RTD or not
+if ("ON_RTD" in os.environ) and (os.environ["ON_RTD"] == "True"):
+    html_context["ON_RTD"] = True
+else:
+    # only change the sidebar when we're not on RTD
+    html_sidebars = {
+        "**": [
+            "sidebar/variant-selector.html",
+            "sidebar/search.html",
+            "sidebar/scroll-start.html",
+            "sidebar/navigation.html",
+            "sidebar/scroll-end.html",
+        ]
+    }
 source_suffix = ".md"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['html', 'README.md']
+exclude_patterns = ['html', 'README.md', '.sphinx']
 
 # Open Graph configuration
 

doc/index.md

@@ -1,4 +1,5 @@
-[![LXD](../.sphinx/_static/download/containers.png)](https://linuxcontainers.org/lxd)
+
+[![LXD](.sphinx/_static/download/containers.png)](https://linuxcontainers.org/lxd)
 
 % Include content from [../README.md](../README.md)
 ```{include} ../README.md