From b647688563aff93a75d7428f4198d41e7155bff1 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:12:51 +0100 Subject: [PATCH 1/9] Use mkdocs extension mike to build versioned docs --- .../documentation-deploy-development.yml | 33 +++++++++++++++++++ ...y.yml => documentation-deploy-release.yml} | 12 ++++--- mkdocs.yml | 3 ++ pyproject.toml | 1 + 4 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/documentation-deploy-development.yml rename .github/workflows/{documentation-deploy.yml => documentation-deploy-release.yml} (62%) diff --git a/.github/workflows/documentation-deploy-development.yml b/.github/workflows/documentation-deploy-development.yml new file mode 100644 index 0000000..779df6e --- /dev/null +++ b/.github/workflows/documentation-deploy-development.yml @@ -0,0 +1,33 @@ +name: Build/Publish Latest Develop Docs + +permissions: write-all + +on: + push: + branches: + - main + workflow_dispatch + +jobs: + build-docs-and-deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3.13 + + - name: Install dependencies + run: | + pip install ".[doc]" + - name: Deploy mkdocs on GitHub Pages + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + TAG_NAME=${{ github.ref_name }} + MAJ_MIN_VERSION=${TAG_NAME%.*} + echo MAJ_MIN_VERSION + mike deploy --push develop diff --git a/.github/workflows/documentation-deploy.yml b/.github/workflows/documentation-deploy-release.yml similarity index 62% rename from .github/workflows/documentation-deploy.yml rename to .github/workflows/documentation-deploy-release.yml index 86b478c..3f780cf 100644 --- a/.github/workflows/documentation-deploy.yml +++ b/.github/workflows/documentation-deploy-release.yml @@ -1,4 +1,4 @@ -name: documentation-deploy +name: Build/Publish Latest Release Docs permissions: write-all @@ -11,7 +11,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - + with: + fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: @@ -19,9 +20,12 @@ jobs: - name: Install dependencies run: | - pip install ".[doc]" + pip install ".[doc]" + - name: Deploy mkdocs on GitHub Pages env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - mkdocs gh-deploy --force + TAG_NAME=${{ github.event.release.tag_name }} + MAJ_MIN_VERSION=${TAG_NAME%.*} + mike deploy --push --update-aliases $MAJ_MIN_VERSION latest diff --git a/mkdocs.yml b/mkdocs.yml index e91ec0b..3459f95 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -99,3 +99,6 @@ extra: social: - icon: fontawesome/brands/github link: https://github.com/MiBiPreT/mibitrans + version: + provider: mike + default: latest \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 6f52fb4..c98255c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,6 +84,7 @@ doc = [ "mkdocstrings[python] ==0.27.0", "mdx-include >=1.4.1", "mkdocs-markdownextradata-plugin >=0.2.5", + "mike >=2.1.3" ] [project.urls] From 64a4ce57be5635741b724d4c82e5e6d8cccd281e Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:15:00 +0100 Subject: [PATCH 2/9] fix typo --- .github/workflows/documentation-deploy-development.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation-deploy-development.yml b/.github/workflows/documentation-deploy-development.yml index 779df6e..731a38b 100644 --- a/.github/workflows/documentation-deploy-development.yml +++ b/.github/workflows/documentation-deploy-development.yml @@ -6,7 +6,7 @@ on: push: branches: - main - workflow_dispatch + workflow_dispatch: jobs: build-docs-and-deploy: From c7ca37d6ba05cc3acc7b1832cf481fe78b5be55f Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:25:46 +0100 Subject: [PATCH 3/9] add extra triggers to dev deployment --- .github/workflows/documentation-deploy-development.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/documentation-deploy-development.yml b/.github/workflows/documentation-deploy-development.yml index 731a38b..b2afe6a 100644 --- a/.github/workflows/documentation-deploy-development.yml +++ b/.github/workflows/documentation-deploy-development.yml @@ -6,6 +6,9 @@ on: push: branches: - main + pull_request: + branches: + - main workflow_dispatch: jobs: From 608a6ba6ec0d09a49b7deaedf12a4febdd2f2cd2 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:28:34 +0100 Subject: [PATCH 4/9] check parameter expansion --- .github/workflows/documentation-deploy-development.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/documentation-deploy-development.yml b/.github/workflows/documentation-deploy-development.yml index b2afe6a..f252403 100644 --- a/.github/workflows/documentation-deploy-development.yml +++ b/.github/workflows/documentation-deploy-development.yml @@ -31,6 +31,6 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | TAG_NAME=${{ github.ref_name }} - MAJ_MIN_VERSION=${TAG_NAME%.*} - echo MAJ_MIN_VERSION + MAJ_MIN_VERSION=${TAG_NAME%/*} + echo $MAJ_MIN_VERSION mike deploy --push develop From 24cdaa1c2307113e148d675b2096e0ed12df9407 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:34:30 +0100 Subject: [PATCH 5/9] create fake gh user for mike --- .github/workflows/documentation-deploy-development.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/documentation-deploy-development.yml b/.github/workflows/documentation-deploy-development.yml index f252403..c46364a 100644 --- a/.github/workflows/documentation-deploy-development.yml +++ b/.github/workflows/documentation-deploy-development.yml @@ -26,6 +26,10 @@ jobs: - name: Install dependencies run: | pip install ".[doc]" + - name: Setup Docs Deploy user + run: | + git config --global user.name "Docs Deploy" + git config --global user.email "docs.deploy@example.co.uk" - name: Deploy mkdocs on GitHub Pages env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 49e66937d25fd732b8f3083092f6d57a8d55abf6 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 15:38:27 +0100 Subject: [PATCH 6/9] Ignore mike serve output --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 57fb2ab..eb877a7 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ coverage.xml .tox docs/_build +site # ide .idea From 2b4c0dbd1d9f979aed1d9ef4043bb99453b11276 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 16:43:26 +0100 Subject: [PATCH 7/9] add alias to dropdown on rendered site --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 3459f95..3c4f020 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,4 +101,5 @@ extra: link: https://github.com/MiBiPreT/mibitrans version: provider: mike - default: latest \ No newline at end of file + default: latest + alias: true From 4254065949e84a1558741ed6d63c2f5136068d76 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 17:22:36 +0100 Subject: [PATCH 8/9] Add user generation to release documentation workflow file --- .github/workflows/documentation-deploy-release.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/documentation-deploy-release.yml b/.github/workflows/documentation-deploy-release.yml index 3f780cf..9c2c317 100644 --- a/.github/workflows/documentation-deploy-release.yml +++ b/.github/workflows/documentation-deploy-release.yml @@ -21,7 +21,10 @@ jobs: - name: Install dependencies run: | pip install ".[doc]" - + - name: Setup Docs Deploy user + run: | + git config --global user.name "Docs Deploy" + git config --global user.email "docs.deploy@example.co.uk" - name: Deploy mkdocs on GitHub Pages env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From bfa275d705b53fdd4968734bbdc7c65cf1232d23 Mon Sep 17 00:00:00 2001 From: Jaro Camphuijsen Date: Mon, 19 Jan 2026 17:37:36 +0100 Subject: [PATCH 9/9] add documentation on versioned docs --- README.dev.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.dev.md b/README.dev.md index 3367ea6..3c203b7 100644 --- a/README.dev.md +++ b/README.dev.md @@ -117,6 +117,10 @@ mkdocs serve This will return a URL (e.g. `http://127.0.0.1:8000/mibitrans/`) where the docs site can be viewed. +Note that this will only create the "non-versioned" documentation, which should be fine for testing changes to the docs. +The versioned documentation is created using the python utility called [mike](https://github.com/jimporter/mike?tab=readme-ov-file#mike) and its corresponding [mkdocs integration](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/). +In general it should not be necessary to test this, but if necessary, use [the mike documentation](https://github.com/jimporter/mike?tab=readme-ov-file#viewing-your-docs) to inspect locally. + ## Versioning Bumping the version across all files is done with [bump-my-version](https://github.com/callowayproject/bump-my-version), e.g.