From e742ef2a051d4a602ef79fd284da5358fdce0472 Mon Sep 17 00:00:00 2001 From: James Wilkinson Date: Tue, 9 Jun 2026 14:48:25 +0100 Subject: [PATCH 1/5] Update docs workflow and add version filtering script --- .github/workflows/docs.yml | 52 ++++++++++++++-------------- docs/archive.md | 5 +++ mkdocs.yml | 1 + scripts/filter_versions.py | 69 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 100 insertions(+), 27 deletions(-) create mode 100644 docs/archive.md create mode 100644 scripts/filter_versions.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 36af9979..b48be7dc 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,33 +31,31 @@ jobs: git config --global user.email "github-actions[bot]@users.noreply.github.com" - name: Fetch gh-pages branch (if exists) - run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet" + run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet" - - name: Deploy documentation + - name: Extract versions.json run: | - if [[ "${GITHUB_REF}" == refs/heads/master ]]; then - echo "→ Deploying latest" - mike deploy latest --push --update-aliases - mike set-default latest --push - elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then - VERSION="${GITHUB_REF#refs/tags/}" - echo "→ Deploying version $VERSION" - mike deploy "$VERSION" --push --update-aliases - mike set-default --push stable - fi - - - name: Copy and commit CNAME file (if exists) + git show origin/gh-pages:versions.json > versions.json + + - name: Filter versions + run: | + python scripts/filter_versions.py versions.json > version_filter_output.json + + - name: Deploy visible versions + run: | + for v in $(jq -r '.visible[]' version_filter_output.json); do + mike deploy --push $v + done + + - name: Deploy hidden versions run: | - git checkout gh-pages - if git checkout master -- docs/CNAME 2>/dev/null; then - mv docs/CNAME . - git add CNAME - if ! git diff --cached --quiet; then - git commit -m "Update CNAME file" - git push origin gh-pages - else - echo "No changes to commit for CNAME" - fi - else - echo "No CNAME file found in master branch" - fi + for v in $(jq -r '.hidden[]' version_filter_output.json); do + mike deploy --push --hidden $v + done + + - name: Set default version + run: | + latest=$(jq -r '.visible[0]' version_filter_output.json) + mike set-default --push $latest + + diff --git a/docs/archive.md b/docs/archive.md new file mode 100644 index 00000000..1a928c24 --- /dev/null +++ b/docs/archive.md @@ -0,0 +1,5 @@ +# Version Archive + +This page lists all TM1py documentation versions. + +Older versions are accessible here even if they’re hidden from the version selector. diff --git a/mkdocs.yml b/mkdocs.yml index c50fdbb5..76709ef6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,6 +21,7 @@ nav: - How to Contribute: how-to-contribute.md - Links: links.md - API Reference: reference/ + - Archive: archive.md exclude_docs: | README.md diff --git a/scripts/filter_versions.py b/scripts/filter_versions.py new file mode 100644 index 00000000..e45ac886 --- /dev/null +++ b/scripts/filter_versions.py @@ -0,0 +1,69 @@ +import json +import re +import sys +from packaging.version import Version + +def parse_version(v): + """Convert 'v2.1.3' → Version('2.1.3')""" + return Version(v.lstrip("v")) + +def load_versions(path): + with open(path, "r") as f: + data = json.load(f) + return [entry["version"] for entry in data["versions"]] + +def group_versions(versions): + parsed = [parse_version(v) for v in versions] + parsed.sort(reverse=True) + + # Group by major.minor + groups = {} + for v in parsed: + key = f"{v.major}.{v.minor}" + groups.setdefault(key, []).append(v) + + return parsed, groups + +def select_visible(parsed, groups): + visible = [] + + # 1. Previous major version (e.g., v2.x if current is v3.x) + current_major = parsed[0].major + previous_major = current_major - 1 + + for v in parsed: + if v.major == previous_major: + visible.append(v) + break # only latest patch of previous major + + # 2. Last 3 minor versions of current major + current_minor_groups = [ + g for g in groups.keys() + if g.startswith(f"{current_major}.") + ] + current_minor_groups.sort(reverse=True) + last_three = current_minor_groups[:3] + + for minor in last_three: + latest_patch = groups[minor][0] # sorted desc + visible.append(latest_patch) + + return visible + +def main(): + path = sys.argv[1] if len(sys.argv) > 1 else "versions.json" + versions = load_versions(path) + parsed, groups = group_versions(versions) + visible = select_visible(parsed, groups) + visible_strings = [f"v{v.public}" for v in visible] + hidden_strings = [v for v in versions if v not in visible_strings] + + output = { + "visible": visible_strings, + "hidden": hidden_strings + } + + print(json.dumps(output, indent=2)) + +if __name__ == "__main__": + main() From f5f540eb3708d8929663e808c2932d88ac5cee0a Mon Sep 17 00:00:00 2001 From: James Wilkinson Date: Tue, 9 Jun 2026 14:57:25 +0100 Subject: [PATCH 2/5] Update docs workflow and add version filtering script --- .github/workflows/docs.yml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b48be7dc..ac179612 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,11 +31,16 @@ jobs: git config --global user.email "github-actions[bot]@users.noreply.github.com" - name: Fetch gh-pages branch (if exists) - run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet" - + run: git fetch origin gh-pages:gh-pages || echo "gh-pages does not exist yet" + - name: Extract versions.json run: | - git show origin/gh-pages:versions.json > versions.json + if git show origin/gh-pages:versions.json > versions.json 2>/dev/null; then + echo "Extracted versions.json from gh-pages" + else + echo '{"versions": []}' > versions.json + echo "Created empty versions.json because gh-pages does not exist yet" + fi - name: Filter versions run: | From 648663c58aa3e95e945f3b53341e8f73e46d6f9c Mon Sep 17 00:00:00 2001 From: James Wilkinson Date: Tue, 9 Jun 2026 15:03:48 +0100 Subject: [PATCH 3/5] Fix in filter_versions.py to allow for first time run with no versions --- scripts/filter_versions.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/scripts/filter_versions.py b/scripts/filter_versions.py index e45ac886..df547ac4 100644 --- a/scripts/filter_versions.py +++ b/scripts/filter_versions.py @@ -53,6 +53,16 @@ def select_visible(parsed, groups): def main(): path = sys.argv[1] if len(sys.argv) > 1 else "versions.json" versions = load_versions(path) + + # In case of first run case as no versions exist yet + if not versions: + output = { + "visible": [], + "hidden": [] + } + print(json.dumps(output, indent=2)) + return + parsed, groups = group_versions(versions) visible = select_visible(parsed, groups) visible_strings = [f"v{v.public}" for v in visible] From cbb548a8aefec340da7a6e5410dab4c02ddc2a65 Mon Sep 17 00:00:00 2001 From: James Wilkinson Date: Tue, 9 Jun 2026 15:08:31 +0100 Subject: [PATCH 4/5] Fix null handling in bash (docs.yml) for first time run --- .github/workflows/docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ac179612..b827e476 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -61,6 +61,11 @@ jobs: - name: Set default version run: | latest=$(jq -r '.visible[0]' version_filter_output.json) - mike set-default --push $latest + if [ "$latest" = "null" ] || [ -z "$latest" ]; then + echo "No visible versions found — skipping set-default" + else + mike set-default --push "$latest" + fi + From 97d6fcf00a0d5f4af66fe86ae0141d40ed64bd0e Mon Sep 17 00:00:00 2001 From: James Wilkinson Date: Tue, 9 Jun 2026 15:18:26 +0100 Subject: [PATCH 5/5] Add tag deployment step to docs.yml --- .github/workflows/docs.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b827e476..d5d3f61a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -46,6 +46,13 @@ jobs: run: | python scripts/filter_versions.py versions.json > version_filter_output.json + - name: Deploy version from tag (if tag triggered) + if: startsWith(github.ref, 'refs/tags/') + run: | + version="v${GITHUB_REF#refs/tags/}" + echo "Deploying version from tag: $version" + mike deploy --push "$version" + - name: Deploy visible versions run: | for v in $(jq -r '.visible[]' version_filter_output.json); do