From 4393c01f460f95d2d4c947a1eee47dc36910627a Mon Sep 17 00:00:00 2001 From: YanNaingWinn Date: Thu, 26 Mar 2026 23:58:56 +0700 Subject: [PATCH 1/2] Add sphinx-multiversion for firmware version-based docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Integrates sphinx-multiversion so each card firmware version (v1.6.1, v1.6.2, …) gets its own docs at docs.cryptnox.com/{version}/. Users can switch between versions via a dropdown in the RTD sidebar. - requirements.txt: add sphinx-multiversion dependency - conf.py: configure smv_* whitelist/pattern settings - deploy.yml: build all versions; root redirect falls back to latest version branch when no tags exist - _templates/versioning.html: version selector dropdown UI - _templates/layout.html: inject version selector into footer block - docs/make.bat: Windows Sphinx build helper - README.md: document versioning workflow and URL structure Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/deploy.yml | 28 ++++++++++++++---- README.md | 40 ++++++++++++++++++++++++++ docs/make.bat | 29 +++++++++++++++++++ docs/source/_templates/layout.html | 1 + docs/source/_templates/versioning.html | 33 +++++++++++++++++++++ docs/source/conf.py | 11 ++++++- requirements.txt | 1 + 7 files changed, 137 insertions(+), 6 deletions(-) create mode 100644 docs/make.bat create mode 100644 docs/source/_templates/versioning.html diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5743524..b26d362 100644 --- a/.github/workflows/deploy.yml +++ b/.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 "" > _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 diff --git a/README.md b/README.md index 1f09bc2..a05f696 100644 --- a/README.md +++ b/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). diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2cd12b7 --- /dev/null +++ b/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 diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 8885973..c0a678a 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -134,3 +134,4 @@ {% endblock %} +{% block footer %}{{ super() }}{% include "versioning.html" %}{% endblock %} diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html new file mode 100644 index 0000000..627b470 --- /dev/null +++ b/docs/source/_templates/versioning.html @@ -0,0 +1,33 @@ +{%- if current_version %} +
+ + + {{- current_version.name }} + + +
+
+
Branches
+ {% for item in versions.branches %} + {% if item.name == current_version.name -%} +
{{ item.name }}
+ {%- else -%} +
{{ item.name }}
+ {%- endif %} + {% endfor %} +
+ {% if versions.tags %} +
+
Tags
+ {% for item in versions.tags %} + {% if item.name == current_version.name -%} +
{{ item.name }}
+ {%- else -%} +
{{ item.name }}
+ {%- endif %} + {% endfor %} +
+ {% endif %} +
+
+{%- endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 29aa576..c2bc5c9 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/requirements.txt b/requirements.txt index cbf1e36..f3e42dd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ sphinx sphinx-rtd-theme +sphinx-multiversion From 1d8f730d15ca8449ce7643df36e0d6000f1b7d1d Mon Sep 17 00:00:00 2001 From: YanNaingWinn Date: Fri, 27 Mar 2026 01:30:31 +0700 Subject: [PATCH 2/2] Pin sphinx<8 for sphinx-multiversion compatibility sphinx-multiversion 0.2.4 is incompatible with Sphinx 8.x (Config.read() signature change). Pin to Sphinx 7.x until a compatible version is available. Co-Authored-By: Claude Sonnet 4.6 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index f3e42dd..4f9e2b5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -sphinx +sphinx<8 sphinx-rtd-theme sphinx-multiversion