Update config for multi-versions

Author: jeremi

.gitignore

@@ -157,3 +157,14 @@ scripts/modules_analysis.json
 
 # Man pages
 share/man/
+
+# Test files for multi-version docs
+test_version_switcher.html
+test-vale-doc.md
+Scripts/test_multiversion*.py
+Scripts/test_multiversion*.sh
+
+# Test deployment directories generated by scripts
+test_deployment/
+test_deployment_quick/
+test_deployment_full/

docs/_static/robots.txt

@@ -0,0 +1,12 @@
+# Robots.txt for OpenSPP Documentation
+# Allow indexing of stable documentation, block preview versions
+
+User-agent: *
+# Block preview documentation branches
+Disallow: /previews/
+
+# Allow stable and versioned releases
+Allow: /
+
+# Sitemap location
+Sitemap: https://docs.openspp.org/sitemap.xml

docs/_templates/layout.html

@@ -1,6 +1,10 @@
 {% extends "sphinx_book_theme/layout.html" %}
 {%- block extrahead %}
 {{ super() }}
+{%- if is_preview %}
+<!-- Prevent search engines from indexing preview documentation -->
+<meta name="robots" content="noindex,nofollow,noarchive">
+{%- endif %}
 <!-- Review Status System - DISABLED
 <link rel="stylesheet" href="{{ pathto('_static/review_status.css', 1) }}" type="text/css" />
 <script src="{{ pathto('_static/review_status_simple.js', 1) }}"></script>

docs/conf.py

@@ -11,6 +11,7 @@
 import re
 import sys
 import logging
+import json
 
 from pathlib import Path
 _logger = logging.getLogger(__name__)
@@ -137,6 +138,17 @@
 # The full version, including alpha/beta/rc tags.
 release = "1.1"
 
+# -- Multi-version configuration ----------------------------------------------
+# Support environment-driven configuration for multi-version builds
+DOCS_VERSION = os.getenv("DOCS_VERSION", "stable")
+DOCS_BASEURL = os.getenv("DOCS_BASEURL", "https://docs.openspp.org/")
+IS_PREVIEW = os.getenv("IS_PREVIEW", "0") == "1"
+
+# Update version display based on environment
+if DOCS_VERSION != "stable":
+    version = DOCS_VERSION
+    release = DOCS_VERSION
+
 # -- General configuration ----------------------------------------------------
 
 # Add any paths that contain templates here, relative to this directory.
@@ -372,11 +384,15 @@
     "**/README.rst",
 ]
 
-html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]
+html_js_files = ["patch_scrollToActive.js", "search_shortcut.js", "version_switcher.js"]
 
-html_extra_path = [
-    "robots.txt",
-]
+# Only include robots.txt for stable builds
+if not IS_PREVIEW:
+    html_extra_path = [
+        "_static/robots.txt",
+    ]
+else:
+    html_extra_path = []
 
 html_static_path = [
     "_static",  # Last path wins. So this one will override the default theme's static files.
@@ -507,6 +523,21 @@
     """,
 }
 
+# Version switcher configuration (for future theme versions)
+# Note: sphinx-book-theme 0.3.3 doesn't have built-in version switcher support
+# Using custom JavaScript implementation in version_switcher.js instead
+html_theme_options["switcher"] = {
+    "json_url": "https://docs.openspp.org/_static/switcher.json", 
+    "version_match": DOCS_VERSION,
+}
+
+# Add announcement banner for preview builds
+if IS_PREVIEW:
+    html_theme_options["announcement"] = f"""
+    <p><strong>⚠️ Preview Documentation</strong>: You are viewing a preview build from branch <code>{DOCS_VERSION}</code>. 
+    For the stable documentation, visit <a href="https://docs.openspp.org/">docs.openspp.org</a></p>
+    """
+
 googleanalytics_id = 'G-RS4T4ZPG52'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -517,7 +548,7 @@
 html_use_index = True
 
 # Used by sphinx_sitemap to generate a sitemap
-html_baseurl = "https://docs.openspp.org/"
+html_baseurl = DOCS_BASEURL
 sitemap_url_scheme = "{link}"
 
 # -- Options for HTML help output -------------------------------------------------
@@ -554,6 +585,7 @@
     "github_repo": "documentation",  # Repo name
     "github_version": "main",  # Version
     "conf_py_path": "/docs/",  # Path in the checkout to the docs root
+    "is_preview": IS_PREVIEW,  # Flag for preview builds to add noindex meta tag
 }
 
 # An extension that allows replacements for code blocks that