Add sphinx-multiversion for firmware version-based docs

.github/workflows/deploy.yml

@@ -2,9 +2,13 @@ name: Deploy Sphinx to GitHub Pages
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
+      - 'v[0-9]+.[0-9]+.[0-9]+'
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - 'v[0-9]+.[0-9]+.[0-9]+'
   workflow_dispatch:
 
 permissions:
@@ -21,6 +25,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch all remote branches
+        run: git fetch --all
 
       - uses: actions/setup-python@v5
         with:
@@ -29,8 +38,17 @@ jobs:
       - name: Install dependencies
         run: pip install -r requirements.txt
 
-      - name: Build Sphinx
-        run: sphinx-build -b html docs/source _site
+      - name: Build all versions with sphinx-multiversion
+        run: sphinx-multiversion docs/source _site
+
+      - name: Add root redirect to latest version
+        run: |
+          LATEST=$(git tag -l 'v*' --sort=-version:refname | head -1)
+          if [ -z "$LATEST" ]; then
+            LATEST=$(git branch -r --list 'origin/v[0-9]*' | sed 's|.*origin/||' | sort -V | tail -1 | tr -d '[:space:]')
+          fi
+          if [ -z "$LATEST" ]; then LATEST="main"; fi
+          echo "<meta http-equiv=\"refresh\" content=\"0; url=./${LATEST}/\">" > _site/index.html
 
       - name: Add CNAME for custom domain
         run: echo "docs.cryptnox.com" > _site/CNAME
@@ -40,7 +58,7 @@ jobs:
           path: _site
 
   deploy:
-    # Only deploy on push to main or manual trigger — not on PR builds
+    # Only deploy on push to main/version branches or manual trigger — not on PR builds
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     environment:
       name: github-pages

README.md

@@ -43,6 +43,46 @@ docs.cryptnox.com/cryptnox-sdk-py/              → cryptnox/cryptnox-sdk-py
 
 ---
 
+## Versioning
+
+Documentation is versioned per card firmware using [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/).
+Each firmware version has a corresponding Git branch named `v{major}.{minor}.{patch}`.
+The `main` branch always reflects the latest development docs.
+
+### URL structure
+
+```
+docs.cryptnox.com/          → redirects to the latest released version
+docs.cryptnox.com/v1.6.1/   → docs for firmware 1.6.1
+docs.cryptnox.com/main/     → latest/development docs
+```
+
+### Adding a new version
+
+```bash
+git checkout main
+git pull
+git checkout -b v1.6.2
+# make any firmware-specific changes to the docs
+git push origin v1.6.2
+```
+
+The CI/CD pipeline automatically builds and deploys the new version alongside all existing versions.
+
+### Updating an existing version
+
+```bash
+git checkout v1.6.1
+# edit docs
+git push origin v1.6.1
+```
+
+### Version selector
+
+Users see a version dropdown at the bottom of the RTD theme sidebar to switch between available versions.
+
+---
+
 ## Get your hardware
 
 Cryptnox smart cards and compatible readers are available at [shop.cryptnox.com](https://shop.cryptnox.com).

docs/make.bat

@@ -0,0 +1,29 @@
+@ECHO OFF
+
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable.
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_templates/layout.html

@@ -134,3 +134,4 @@
 </script>
 {% endblock %}
 
+{% block footer %}{{ super() }}{% include "versioning.html" %}{% endblock %}

docs/source/_templates/versioning.html

@@ -0,0 +1,33 @@
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> </span>
+    {{- current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    <dl>
+      <dt>Branches</dt>
+      {% for item in versions.branches %}
+        {% if item.name == current_version.name -%}
+          <dd><strong>{{ item.name }}</strong></dd>
+        {%- else -%}
+          <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+        {%- endif %}
+      {% endfor %}
+    </dl>
+    {% if versions.tags %}
+    <dl>
+      <dt>Tags</dt>
+      {% for item in versions.tags %}
+        {% if item.name == current_version.name -%}
+          <dd><strong>{{ item.name }}</strong></dd>
+        {%- else -%}
+          <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+        {%- endif %}
+      {% endfor %}
+    </dl>
+    {% endif %}
+  </div>
+</div>
+{%- endif %}

docs/source/conf.py

@@ -9,7 +9,7 @@
 
 # -- General configuration ---------------------------------------------------
 
-extensions = []
+extensions = ['sphinx_multiversion']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
@@ -54,3 +54,12 @@
 html_show_sourcelink = False
 html_copy_source = False
 html_show_sphinx = False
+
+# -- sphinx-multiversion config ----------------------------------------------
+
+smv_branch_whitelist   = r'^(main|v\d+\.\d+\.\d+)$'
+smv_tag_whitelist      = r'^v\d+\.\d+\.\d+$'
+smv_remote_whitelist   = r'^origin$'
+smv_released_pattern   = r'^refs/(heads/v\d+\.\d+\.\d+|tags/v\d+\.\d+\.\d+)$'
+smv_outputdir_format   = '{ref.name}'
+smv_prefer_remote_refs = False

requirements.txt

@@ -1,2 +1,3 @@
-sphinx
+sphinx<8
 sphinx-rtd-theme
+sphinx-multiversion