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..4f9e2b5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ -sphinx +sphinx<8 sphinx-rtd-theme +sphinx-multiversion