Add relays to unversioned targets (#19)

urfeex · web-flow · commit 00a84537bfa0 · 2026-04-14T14:52:25.000+02:00
This is basically a compatibility layer so old links to the unversioned
pages will continue to work.
diff --git a/Makefile b/Makefile
@@ -27,7 +27,7 @@ html: clone-subrepos
 	export ROS_DISTRO="$$ros"; \
 	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html/$$ros" $(SPHINXOPTS) $(O)
 
-# Humble, Jazzy, Kilted, Rolling; optional root index redirect (see script)
+# Jazzy, Kilted, Rolling; version-less pages redirect to chosen distro (see script)
 html-all:
 	@./scripts/build_docs.sh
 
diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh
@@ -18,6 +18,20 @@ SUBREPOS=(
 DISTROS=(jazzy kilted rolling)
 REDIRECT_TARGET="${DOCUMENTATION_ROOT_REDIRECT:-rolling}"
 
+# Relative URL from _build/html/<relpath> to _build/html/<target>/<relpath>
+redirect_url_to_versioned() {
+  local versionless_relpath="$1"
+  local target="$2"
+  local dir
+  dir="$(dirname "$versionless_relpath")"
+  local up=""
+  while [[ "$dir" != "." ]]; do
+    up="../${up}"
+    dir="$(dirname "$dir")"
+  done
+  printf '%s' "${up}${target}/${versionless_relpath}"
+}
+
 clean_subrepos() {
   rm -rf "${SUBREPOS[@]}"
 }
@@ -31,29 +45,43 @@ build_one() {
   sphinx-build -b html . "${ROOT}/_build/html/${distro}"
 }
 
-write_root_redirect() {
+# Place a version-less HTML stub for each page in <target>/ so that
+# /path/to/page.html redirects to /<target>/path/to/page.html (GitHub Pages).
+write_versionless_redirects() {
   local target="$1"
-  cat > "${ROOT}/_build/html/index.html" <<EOF
+  local src="${ROOT}/_build/html/${target}"
+  if [[ ! -d "$src" ]]; then
+    echo "write_versionless_redirects: missing ${src}" >&2
+    return 1
+  fi
+  while IFS= read -r -d '' f; do
+    local relpath="${f#"${src}/"}"
+    local dest="${ROOT}/_build/html/${relpath}"
+    mkdir -p "$(dirname "$dest")"
+    local url
+    url="$(redirect_url_to_versioned "$relpath" "$target")"
+    cat > "$dest" <<EOF
 <!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
-  <meta http-equiv="refresh" content="0; url=${target}/index.html">
-  <link rel="canonical" href="${target}/index.html">
+  <meta http-equiv="refresh" content="0; url=${url}">
+  <link rel="canonical" href="${url}">
   <title>Universal Robots ROS 2 Driver Documentation</title>
 </head>
 <body>
-  <p><a href="${target}/index.html">Continue to ${target} documentation</a>.</p>
+  <p><a href="${url}">Continue to ${target} documentation</a>.</p>
 </body>
 </html>
 EOF
+  done < <(find "$src" -name '*.html' -print0)
 }
 
 if [[ $# -eq 0 ]]; then
   for d in "${DISTROS[@]}"; do
     build_one "$d"
   done
-  write_root_redirect "$REDIRECT_TARGET"
+  write_versionless_redirects "$REDIRECT_TARGET"
 else
   for d in "$@"; do
     build_one "$d"
