From 06abec4f87fbc7cd2c4773bd1be28c09932ce5af Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Mon, 5 Aug 2024 15:05:20 -0400 Subject: [PATCH 1/4] docs: configure multiple versions dropdown --- .github/workflows/docs.yml | 14 +++++++++++--- mkdocs.yml | 4 ++++ 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0f95810..4ee1d23 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,4 +1,4 @@ -name: docs +name: mkdocs on: workflow_dispatch: push: @@ -6,8 +6,12 @@ on: - main paths: - "docs/**" - - mkdocs.yml + - "**.md" - .github/workflows/docs.yml + - mkdocs.yml + +env: + actor: "41898282+github-actions[bot]" jobs: deploy: @@ -16,7 +20,11 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-python@v2 with: - python-version: 3.11 + python-version: 3.9 + - name: git config + run: | + git config --local user.email "${actor}@users.noreply.github.com" + git config --local user.name "$actor" - run: pip install --upgrade pip - run: pip install -r docs/requirements.txt - run: mkdocs gh-deploy --force diff --git a/mkdocs.yml b/mkdocs.yml index 018fa3f..91e0d8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,6 +46,10 @@ plugins: - git-revision-date - minify: minify_html: true + - mike: + alias_type: symlink + canonical_version: latest + version_selector: true # Customization extra: From 2ba79e9ef1788d49c189ad1e025b32948b30bdab Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Mon, 5 Aug 2024 15:09:50 -0400 Subject: [PATCH 2/4] docs: fix material emoji extensions --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 91e0d8e..130fb76 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -78,8 +78,8 @@ markdown_extensions: - pymdownx.critic - pymdownx.details - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg - pymdownx.highlight - pymdownx.inlinehilite - pymdownx.keys From 1c3d4cf029b9f4b35dcdb0a338daa932aeeb795d Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Mon, 5 Aug 2024 15:21:05 -0400 Subject: [PATCH 3/4] chore: update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f765f89..e6f3c17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ - You can now cite XAVIER with the DOI [10.5281/zenodo.12727315](https://doi.org/10.5281/zenodo.12727315). (#88, @kelly-sovacool) - Minor documentation improvements. (#92, @kelly-sovacool) - Minor documentation rendering improvements (#93, @samarth8392) +- The docs website now has a dropdown menu to select which version to view. The latest release is shown by default. (#150, @kelly-sovacool) ## XAVIER 3.0.3 From e32863fed0022a695e0d8f96b9c381824ef0e718 Mon Sep 17 00:00:00 2001 From: Kelly Sovacool Date: Mon, 5 Aug 2024 15:27:25 -0400 Subject: [PATCH 4/4] ci: use mike extension for mkdocs --- .github/workflows/docs.yml | 65 ++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4ee1d23..35ea4e3 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,6 +1,9 @@ -name: mkdocs +name: docs on: workflow_dispatch: + release: + types: + - published push: branches: - main @@ -12,19 +15,67 @@ on: env: actor: "41898282+github-actions[bot]" + GH_TOKEN: ${{ github.token }} jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-python@v2 + - uses: actions/checkout@v4 with: - python-version: 3.9 + fetch-depth: 0 + - uses: actions/setup-python@v5 + with: + python-version: 3.11 + cache: pip + - run: pip install --upgrade pip -r docs/requirements.txt - name: git config run: | git config --local user.email "${actor}@users.noreply.github.com" git config --local user.name "$actor" - - run: pip install --upgrade pip - - run: pip install -r docs/requirements.txt - - run: mkdocs gh-deploy --force + gh release list > releases.tsv + - name: get version tag & alias + shell: python {0} + run: | + import os + import re + import warnings + + release_tag = '' + with open('releases.tsv', 'r') as infile: + for line in infile: + release_name, latest, tag, timestamp = line.strip().split('\t') + if latest == "Latest": + release_tag = tag.strip('v') + break + if not release_tag: + warnings.warn("No latest release found") + + with open('VERSION', 'r') as infile: + current_version = infile.read().strip() + + if current_version == release_tag: + docs_alias = 'latest' + docs_version = release_tag + else: + semver_pattern = '(?P0|[1-9]\d*)\.(?P0|[1-9]\d*)\.(?P0|[1-9]\d*)(?:-(?P(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?' + release_semver = re.match(semver_pattern, release_tag) + current_semver = re.match(semver_pattern, current_version) + + groups = ['major', 'minor', 'patch'] + if current_semver.group('prerelease') and any([current_semver.group(grp) >= release_semver.group(grp) for grp in groups]): + docs_alias = '' + docs_version = 'dev' + else: + raise ValueError(f"current version {current_version} is not greater than latest release {release_tag}") + + with open(os.getenv("GITHUB_ENV"), 'a') as out_env: + out_env.write(f"VERSION={docs_version}\n") + out_env.write(f"ALIAS={docs_alias}\n") + + - name: deploy docs + run: | + mike deploy ${{ env.VERSION }} ${{ env.ALIAS }} \ + --push \ + --update-aliases \ + --branch gh-pages