From 36489a8744a90fad16f673e7b5bd28887d95e86d Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Wed, 17 Jul 2024 16:11:19 +0200 Subject: [PATCH 01/17] Add utilities for multi-version documentation --- docs/scripts/add_version.py | 72 +++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/scripts/add_version.py diff --git a/docs/scripts/add_version.py b/docs/scripts/add_version.py new file mode 100644 index 000000000..db3228569 --- /dev/null +++ b/docs/scripts/add_version.py @@ -0,0 +1,72 @@ +"""Utilities for adding versions when building the documentation.""" + +import sys +from pathlib import Path + + +def add_version_to_selector_page(version: str) -> None: + """Add the newly built version to the version selection overview. + + Args: + version: The version that should be added. + """ + indent = " " + new_line = ( + f"{indent}
  • {version}' + "
    • \n" + ) + file = Path("versions.html") + modified_lines = [] + with file.open(mode="r") as f: + lines = f.readlines() + for line in lines: + modified_lines.append(line) + # Add new line at correct position which is in the first line after stable + if "Stable" in line: + modified_lines.append(new_line) + with file.open(mode="w") as f: + f.writelines(modified_lines) + + +def adjust_version_in_sidebar(version: str) -> None: + """Adjust the shown version in the sidebar. + + Args: + version: The version that should be injected into the sidebar. + """ + prefix = '
  • ' + link = "https://avhopp.github.io/baybe_dev/versions" + line_to_replace = ( + f'{prefix}Versions
    • ' + ) + new_line = ( + f'{prefix}V: {version}' + ) + path = Path(version) + if path.exists(): + # Recursively check all HTML files + for file in path.rglob("*.html"): + modified_lines = [] + with file.open(mode="r") as f: + lines = f.readlines() + for line in lines: + if line.strip() == line_to_replace: + modified_lines.append(new_line) + else: + modified_lines.append(line) + with file.open(mode="w") as f: + f.writelines(modified_lines) + + +if __name__ == "__main__": + chosen_method = sys.argv[1] + version = sys.argv[2] + if chosen_method == "selector_page": + print(f"Adding {version=} to version selector page") + add_version_to_selector_page(version) + elif chosen_method == "sidebar": + adjust_version_in_sidebar(version) + print(f"Adding {version=} to sidebar") + else: + print(f"Invalid arguments {sys.argv} were chosen!") From 8ed2eae3f784a8176cb41970a19d749cc1861ab6 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 14 May 2024 17:40:01 +0200 Subject: [PATCH 02/17] Adjust doc building workflow for multi version --- .github/workflows/docs.yml | 88 +++++++++++++++++++++++--------------- docs/index.md | 1 + 2 files changed, 55 insertions(+), 34 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bc7b0b18a..7559c333e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,20 +1,12 @@ name: Documentation on: + push: + branches: + - main release: types: - published - workflow_dispatch: - inputs: - force: - description: 'Force' - default: false - required: false - type: boolean - tag: - description: 'Specify tag (empty builds branch HEAD)' - required: false - default: '' concurrency: group: ${{ github.workflow }} @@ -24,35 +16,63 @@ jobs: build: runs-on: ubuntu-latest permissions: - contents: read + contents: write pages: write id-token: write steps: - uses: actions/checkout@v4 with: - ref: ${{ inputs.tag || github.ref }} + ref: ${{ github.ref }} - uses: actions/setup-python@v5 with: {python-version: "3.10"} - name: Install tox run: pip install tox-uv - - name: Build Docs ${{ inputs.force == true && '(Force)' || '' }} - run: tox -e docs-py310 ${{ inputs.force == true && '-- -f -r' || '-- -r' }} - - name: Upload docs artifact - uses: actions/upload-pages-artifact@v1 - with: - path: 'docs/build' - - deploy: - needs: build - runs-on: ubuntu-latest - permissions: - contents: read - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v1 + - name: Build Docs + run: tox -e docs-py310 -- -r + - name: Prepare gh-pages branch with HTML output from Sphinx + run: | + git fetch origin gh-pages:gh-pages + git checkout gh-pages + if [ -d "latest" ]; then + rm -rf latest + fi + mkdir ./latest + cp -r docs/build/* ./latest + echo "Successfully copied into latest" + if ${{ github.event_name == 'release' }}; then + FOLDER=${{github.event.release.tag_name}} + mkdir ./$FOLDER + cp -r docs/build/* ./$FOLDER + echo "Copying files into stable folder" + if [ -d "stable" ]; then + echo "Deleting old stable folder." + rm -rf stable + fi + mkdir ./stable + cp -rv docs/build/* ./stable + echo "Successfully copied into stable folder" + fi + - name: Update gh-pages branch + run: | + git config --local user.email "sphinx-upload[bot]@users.noreply.github.com" + git config --local user.name "sphinx-upload[bot]" + git_hash=$(git rev-parse --short "$GITHUB_SHA") + git fetch origin main:main + git show main:docs/scripts/add_version.py > add_version.py + python add_version.py sidebar latest + git add -f latest + git commit --allow-empty -m "Sphinx documentation for ${git_hash}" + if ${{ github.event_name == 'release' }}; then + FOLDER=${{github.event.release.tag_name}} + git add -f $FOLDER + echo "Adding stable as a separate folder" + git add -f stable + echo "Inserting announcement banner to documentation and add link for selector" + python add_version.py selector_page $FOLDER + python add_version.py sidebar $FOLDER + python add_version.py sidebar stable + rm add_version.py + git add . + git commit -m "Add link to version to selector page and add banner" + fi + git push origin gh-pages diff --git a/docs/index.md b/docs/index.md index 3a43a9176..e1b9c7e94 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,6 +34,7 @@ Known Issues Changelog Github License +Versions ``` # Indices and Tables From a79eac380533ecda512e3cdc095ddd167c43c875 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 18 Jul 2024 13:54:33 +0200 Subject: [PATCH 03/17] Add functionality for adding banners in numbered versions --- .github/workflows/docs.yml | 6 +++--- docs/scripts/add_version.py | 29 ++++++++++++++++++++++++----- 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7559c333e..895d3e6a7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -59,7 +59,7 @@ jobs: git_hash=$(git rev-parse --short "$GITHUB_SHA") git fetch origin main:main git show main:docs/scripts/add_version.py > add_version.py - python add_version.py sidebar latest + python add_version.py html latest git add -f latest git commit --allow-empty -m "Sphinx documentation for ${git_hash}" if ${{ github.event_name == 'release' }}; then @@ -69,8 +69,8 @@ jobs: git add -f stable echo "Inserting announcement banner to documentation and add link for selector" python add_version.py selector_page $FOLDER - python add_version.py sidebar $FOLDER - python add_version.py sidebar stable + python add_version.py html $FOLDER + python add_version.py html stable rm add_version.py git add . git commit -m "Add link to version to selector page and add banner" diff --git a/docs/scripts/add_version.py b/docs/scripts/add_version.py index db3228569..4aca7c5ba 100644 --- a/docs/scripts/add_version.py +++ b/docs/scripts/add_version.py @@ -29,8 +29,11 @@ def add_version_to_selector_page(version: str) -> None: f.writelines(modified_lines) -def adjust_version_in_sidebar(version: str) -> None: - """Adjust the shown version in the sidebar. +def adjust_version_to_html(version: str) -> None: + """Adjust the shown version in the HTML files. + + This method includes the current version in the sidebar of all HTML files and + additionally adds a banner warning when the documentation is not ``stable``. Args: version: The version that should be injected into the sidebar. @@ -43,6 +46,17 @@ def adjust_version_in_sidebar(version: str) -> None: new_line = ( f'{prefix}V: {version}' ) + # The content of the announcement that might be added. + announcement = "You are not viewing the documentation of the stable version." + # Actual HTML code that will be inserted + announcement_html = ( + """
    \n""" + """ \n""" + """
    \n""" + ) + add_announcement = version != "stable" path = Path(version) if path.exists(): # Recursively check all HTML files @@ -51,6 +65,11 @@ def adjust_version_in_sidebar(version: str) -> None: with file.open(mode="r") as f: lines = f.readlines() for line in lines: + # Check if we need to add the announcement + if add_announcement: + # Add announcement at correct position + if line.strip() == '
    ': + modified_lines.insert(-2, announcement_html) if line.strip() == line_to_replace: modified_lines.append(new_line) else: @@ -65,8 +84,8 @@ def adjust_version_in_sidebar(version: str) -> None: if chosen_method == "selector_page": print(f"Adding {version=} to version selector page") add_version_to_selector_page(version) - elif chosen_method == "sidebar": - adjust_version_in_sidebar(version) - print(f"Adding {version=} to sidebar") + elif chosen_method == "html": + adjust_version_to_html(version) + print(f"Adding {version=} to HTML") else: print(f"Invalid arguments {sys.argv} were chosen!") From 121fd2b451c3e31d0ae39d73f05012a2de8b3adc Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 18 Jul 2024 14:28:21 +0200 Subject: [PATCH 04/17] Update CHANGELOG.md --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fcb475fc..b6e2266d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] +### Added +- Multi version documentation + ## [0.10.0] - 2024-08-02 ### Breaking Changes - Providing an explicit `batch_size` is now mandatory when asking for recommendations From e8e34629d38e4b854c2e49fab1b3b8901d213656 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Sun, 21 Jul 2024 16:08:23 +0200 Subject: [PATCH 05/17] Make workflow more modular --- .github/workflows/docs.yml | 70 +++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 31 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 895d3e6a7..b1663e1c1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,7 +29,11 @@ jobs: run: pip install tox-uv - name: Build Docs run: tox -e docs-py310 -- -r - - name: Prepare gh-pages branch with HTML output from Sphinx + - name: Configure sphinx bot for pushing and fetch branches + run: | + git config --local user.email "sphinx-upload[bot]@users.noreply.github.com" + git config --local user.name "sphinx-upload[bot]" + - name: Copy latest folder to gh-pages branch run: | git fetch origin gh-pages:gh-pages git checkout gh-pages @@ -39,40 +43,44 @@ jobs: mkdir ./latest cp -r docs/build/* ./latest echo "Successfully copied into latest" - if ${{ github.event_name == 'release' }}; then - FOLDER=${{github.event.release.tag_name}} - mkdir ./$FOLDER - cp -r docs/build/* ./$FOLDER - echo "Copying files into stable folder" - if [ -d "stable" ]; then - echo "Deleting old stable folder." - rm -rf stable - fi - mkdir ./stable - cp -rv docs/build/* ./stable - echo "Successfully copied into stable folder" + - if: ${{ github.event_name == 'release' }} + name: Copy stable folder to gh-pages branch when releasing + run: | + FOLDER=${{github.event.release.tag_name}} + mkdir ./$FOLDER + cp -r docs/build/* ./$FOLDER + echo "Copying files into stable folder" + if [ -d "stable" ]; then + echo "Deleting old stable folder." + rm -rf stable fi - - name: Update gh-pages branch + mkdir ./stable + cp -rv docs/build/* ./stable + echo "Successfully copied into stable folder" + - name: Update gh-pages branch for latest run: | - git config --local user.email "sphinx-upload[bot]@users.noreply.github.com" - git config --local user.name "sphinx-upload[bot]" git_hash=$(git rev-parse --short "$GITHUB_SHA") git fetch origin main:main git show main:docs/scripts/add_version.py > add_version.py python add_version.py html latest git add -f latest - git commit --allow-empty -m "Sphinx documentation for ${git_hash}" - if ${{ github.event_name == 'release' }}; then - FOLDER=${{github.event.release.tag_name}} - git add -f $FOLDER - echo "Adding stable as a separate folder" - git add -f stable - echo "Inserting announcement banner to documentation and add link for selector" - python add_version.py selector_page $FOLDER - python add_version.py html $FOLDER - python add_version.py html stable - rm add_version.py - git add . - git commit -m "Add link to version to selector page and add banner" - fi - git push origin gh-pages + git commit -m "Sphinx documentation for ${git_hash} (latest)" + - if: ${{ github.event_name == 'release' }} + name: Add new stable and numbered version to gh-pages branch + run: | + FOLDER=${{github.event.release.tag_name}} + echo "Adding numbered folder" + git add -f $FOLDER + git commit -m "Sphinx documentation for ${git_hash} (${FOLDER})" + echo "Adding stable as a separate folder" + git add -f stable + git commit -m "Sphinx documentation for ${git_hash} (stable)" + echo "Inserting announcement banner to documentation and add link for selector" + python add_version.py selector_page $FOLDER + python add_version.py html $FOLDER + python add_version.py html stable + rm add_version.py + git add . + git commit -m "Add link to version to selector page and add banner" + - name: Push changes to gh-pages branch + run: git push origin gh-pages From 37c8d974aaffd421ae09e9efe0aec9af3d99ff1f Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 09:44:23 +0200 Subject: [PATCH 06/17] Make versions a section in the sidebar --- docs/index.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index e1b9c7e94..8b49d0e10 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,14 @@ Examples :relative-docs: docs/ ``` +```{toctree} +:titlesonly: +:caption: Versions +:hidden: + +Versions +``` + ```{eval-rst} .. autosummary:: :toctree: _autosummary @@ -34,7 +42,6 @@ Known Issues Changelog Github License -Versions ``` # Indices and Tables From 527cdde9b4d51ded2b4315914f34aaba871eff76 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:00:30 +0200 Subject: [PATCH 07/17] Change colors for announcement banner --- docs/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 60516ae53..2978e5710 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -188,6 +188,9 @@ # Color of the search text and icon "color-sidebar-search-text": "white", "color-sidebar-search-icon": BROWN, + # The announcement background and text color + "color-announcement-background": "red", + "color-announcement-text": "black", }, # Colors for dark mode. "dark_css_variables": { @@ -222,6 +225,9 @@ "color-toc-item-text--active": BROWN, # Color of search bar when clicking search "color-sidebar-search-background--focus": DARK_BLUE, + # The announcement background and text color + "color-announcement-background": "red", + "color-announcement-text": "black", }, # Logos. Location is relative to _static folder. "light_logo": "logo1.svg", # Logo for light mode From 561b5e0b26cb417e8ec2f578dfba60c033e8eae1 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:35:50 +0200 Subject: [PATCH 08/17] Add manual trigger for building latest --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b1663e1c1..0273b780f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,6 +7,8 @@ on: release: types: - published + workflow_dispatch: # Allow manually triggering the workflow + concurrency: group: ${{ github.workflow }} From 2ad6e0ef93c9d959fa5cede6eab1b1586510b3e6 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:37:52 +0200 Subject: [PATCH 09/17] Add link to stable version in annoucement banner --- docs/scripts/add_version.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/scripts/add_version.py b/docs/scripts/add_version.py index 4aca7c5ba..f097099da 100644 --- a/docs/scripts/add_version.py +++ b/docs/scripts/add_version.py @@ -46,8 +46,11 @@ def adjust_version_to_html(version: str) -> None: new_line = ( f'{prefix}V: {version}' ) + link_to_stable = 'stable' # The content of the announcement that might be added. - announcement = "You are not viewing the documentation of the stable version." + announcement = ( + f"You are not viewing the documentation of the {link_to_stable} version." + ) # Actual HTML code that will be inserted announcement_html = ( """
    \n""" From f4caee7d539c2f8084776c43d56014888ba220e9 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 25 Jul 2024 10:38:35 +0200 Subject: [PATCH 10/17] Change color of annoucement banner --- docs/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2978e5710..adb977025 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -189,8 +189,8 @@ "color-sidebar-search-text": "white", "color-sidebar-search-icon": BROWN, # The announcement background and text color - "color-announcement-background": "red", - "color-announcement-text": "black", + "color-announcement-background": LIGHT_BLUE, + "color-announcement-text": LIGHT_GRAY, }, # Colors for dark mode. "dark_css_variables": { @@ -226,8 +226,8 @@ # Color of search bar when clicking search "color-sidebar-search-background--focus": DARK_BLUE, # The announcement background and text color - "color-announcement-background": "red", - "color-announcement-text": "black", + "color-announcement-background": LIGHT_BLUE, + "color-announcement-text": LIGHT_GRAY, }, # Logos. Location is relative to _static folder. "light_logo": "logo1.svg", # Logo for light mode From 2122bbf1660cecd00287d5a61a4fa51b8469b4d3 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 25 Jul 2024 10:40:27 +0200 Subject: [PATCH 11/17] Move Version to the top of the sidebar --- docs/index.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8b49d0e10..326e57eea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,10 @@ +```{toctree} +:titlesonly: +:hidden: + +Versions +``` + ```{toctree} :maxdepth: 2 :titlesonly: @@ -13,14 +20,6 @@ Examples :relative-docs: docs/ ``` -```{toctree} -:titlesonly: -:caption: Versions -:hidden: - -Versions -``` - ```{eval-rst} .. autosummary:: :toctree: _autosummary From 7cd47ce8fca06441860a246c5b08ed3cbd4f68b5 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Sun, 28 Jul 2024 13:48:00 +0200 Subject: [PATCH 12/17] Replace V: by Version: --- docs/scripts/add_version.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/scripts/add_version.py b/docs/scripts/add_version.py index f097099da..93b44cba5 100644 --- a/docs/scripts/add_version.py +++ b/docs/scripts/add_version.py @@ -39,12 +39,11 @@ def adjust_version_to_html(version: str) -> None: version: The version that should be injected into the sidebar. """ prefix = '
  • ' + html_class = "reference external" link = "https://avhopp.github.io/baybe_dev/versions" - line_to_replace = ( - f'{prefix}Versions
    • ' - ) + line_to_replace = f'{prefix}Versions' new_line = ( - f'{prefix}V: {version}' + f'{prefix}Version: {version}' ) link_to_stable = 'stable' # The content of the announcement that might be added. From aa0e994096d48b52ea14c4ea8bcb350170702b60 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Sun, 28 Jul 2024 14:47:15 +0200 Subject: [PATCH 13/17] Change workflow --- .github/workflows/docs.yml | 66 +++++++++++--------- docs/scripts/add_version.py | 93 ---------------------------- docs/scripts/utils.py | 117 ++++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+), 123 deletions(-) delete mode 100644 docs/scripts/add_version.py diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0273b780f..4099298ea 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,54 +35,60 @@ jobs: run: | git config --local user.email "sphinx-upload[bot]@users.noreply.github.com" git config --local user.name "sphinx-upload[bot]" - - name: Copy latest folder to gh-pages branch - run: | git fetch origin gh-pages:gh-pages git checkout gh-pages + git fetch origin main:main + git show main:docs/scripts/utils.py > utils.py + - name: Check for Hotfix + id: hotfix + run: | + pip install packaging + git fetch --tags + tags=$(git tag -l) + if ${{ github.event_name == 'release' }}; then + HOTFIX_VERSION=$(python utils.py hotfix "${{github.event.release.tag_name}}" "$tags") + else + HOTFIX_VERSION="False" + fi + echo "$HOTFIX_VERSION" + echo "hotfix=$HOTFIX_VERSION" >> "$GITHUB_OUTPUT" + - name: Verify setting of hotfix + run: | + echo "The value of hotfix is ${{ steps.hotfix.outputs.hotfix }}" + - if: ${{ steps.hotfix.outputs.hotfix == 'False'}} + name: Copy latest folder to gh-pages branch and update branch + run: | if [ -d "latest" ]; then rm -rf latest fi mkdir ./latest cp -r docs/build/* ./latest echo "Successfully copied into latest" + python utils.py html latest + git add -f latest - if: ${{ github.event_name == 'release' }} - name: Copy stable folder to gh-pages branch when releasing + name: Create numbered version run: | FOLDER=${{github.event.release.tag_name}} mkdir ./$FOLDER cp -r docs/build/* ./$FOLDER - echo "Copying files into stable folder" + python utils.py selector_page $FOLDER + python utils.py html $FOLDER + git add -f $FOLDER + git add -f versions.html + - if: ${{ (github.event_name == 'release') && (steps.hotfix.outputs.hotfix == 'False') }} + name: Copy stable folder to gh-pages branch when releasing + run: | if [ -d "stable" ]; then - echo "Deleting old stable folder." rm -rf stable fi mkdir ./stable cp -rv docs/build/* ./stable - echo "Successfully copied into stable folder" - - name: Update gh-pages branch for latest - run: | - git_hash=$(git rev-parse --short "$GITHUB_SHA") - git fetch origin main:main - git show main:docs/scripts/add_version.py > add_version.py - python add_version.py html latest - git add -f latest - git commit -m "Sphinx documentation for ${git_hash} (latest)" - - if: ${{ github.event_name == 'release' }} - name: Add new stable and numbered version to gh-pages branch - run: | - FOLDER=${{github.event.release.tag_name}} - echo "Adding numbered folder" - git add -f $FOLDER - git commit -m "Sphinx documentation for ${git_hash} (${FOLDER})" - echo "Adding stable as a separate folder" + python utils.py html stable git add -f stable - git commit -m "Sphinx documentation for ${git_hash} (stable)" - echo "Inserting announcement banner to documentation and add link for selector" - python add_version.py selector_page $FOLDER - python add_version.py html $FOLDER - python add_version.py html stable - rm add_version.py - git add . - git commit -m "Add link to version to selector page and add banner" + - name: Create git commit + run: | + git_hash=$(git rev-parse --short "$GITHUB_SHA") + git commit -m "Sphinx documentation for ${git_hash}" - name: Push changes to gh-pages branch run: git push origin gh-pages diff --git a/docs/scripts/add_version.py b/docs/scripts/add_version.py deleted file mode 100644 index 93b44cba5..000000000 --- a/docs/scripts/add_version.py +++ /dev/null @@ -1,93 +0,0 @@ -"""Utilities for adding versions when building the documentation.""" - -import sys -from pathlib import Path - - -def add_version_to_selector_page(version: str) -> None: - """Add the newly built version to the version selection overview. - - Args: - version: The version that should be added. - """ - indent = " " - new_line = ( - f"{indent}
  • {version}' - "
    • \n" - ) - file = Path("versions.html") - modified_lines = [] - with file.open(mode="r") as f: - lines = f.readlines() - for line in lines: - modified_lines.append(line) - # Add new line at correct position which is in the first line after stable - if "Stable" in line: - modified_lines.append(new_line) - with file.open(mode="w") as f: - f.writelines(modified_lines) - - -def adjust_version_to_html(version: str) -> None: - """Adjust the shown version in the HTML files. - - This method includes the current version in the sidebar of all HTML files and - additionally adds a banner warning when the documentation is not ``stable``. - - Args: - version: The version that should be injected into the sidebar. - """ - prefix = '
  • ' - html_class = "reference external" - link = "https://avhopp.github.io/baybe_dev/versions" - line_to_replace = f'{prefix}Versions
    • ' - new_line = ( - f'{prefix}Version: {version}' - ) - link_to_stable = 'stable' - # The content of the announcement that might be added. - announcement = ( - f"You are not viewing the documentation of the {link_to_stable} version." - ) - # Actual HTML code that will be inserted - announcement_html = ( - """
    \n""" - """ \n""" - """
    \n""" - ) - add_announcement = version != "stable" - path = Path(version) - if path.exists(): - # Recursively check all HTML files - for file in path.rglob("*.html"): - modified_lines = [] - with file.open(mode="r") as f: - lines = f.readlines() - for line in lines: - # Check if we need to add the announcement - if add_announcement: - # Add announcement at correct position - if line.strip() == '
    ': - modified_lines.insert(-2, announcement_html) - if line.strip() == line_to_replace: - modified_lines.append(new_line) - else: - modified_lines.append(line) - with file.open(mode="w") as f: - f.writelines(modified_lines) - - -if __name__ == "__main__": - chosen_method = sys.argv[1] - version = sys.argv[2] - if chosen_method == "selector_page": - print(f"Adding {version=} to version selector page") - add_version_to_selector_page(version) - elif chosen_method == "html": - adjust_version_to_html(version) - print(f"Adding {version=} to HTML") - else: - print(f"Invalid arguments {sys.argv} were chosen!") diff --git a/docs/scripts/utils.py b/docs/scripts/utils.py index e7f933947..849c75cb6 100644 --- a/docs/scripts/utils.py +++ b/docs/scripts/utils.py @@ -1,5 +1,11 @@ """This file contains some utility function for building the documentation.""" +import re +import sys +from pathlib import Path + +from packaging.version import Version + def adjust_pictures( file_path: str, match: str, light_version: str, dark_version: str @@ -40,3 +46,114 @@ def adjust_pictures( with open(file_path, "w") as file: file.writelines(lines) + + +def add_version_to_selector_page(version: str) -> None: + """Add the newly built version to the version selection overview. + + Args: + version: The version that should be added. + """ + indent = " " + new_line = ( + f"{indent}
  • {version}' + "
    • \n" + ) + file = Path("versions.html") + modified_lines = [] + # Regular expression pattern to match the version number in the format X.Y.Z + pattern = r"\b\d+\.\d+\.\d+\b" + # Indices for memorizing the index of the line containing "Stable" and the last + # version that was larger than the one to be inserted + stable_index = -1 + last_version_index = -1 + with file.open(mode="r") as f: + lines = f.readlines() + for ind, line in enumerate(lines): + # Search for the version number in the current line + if version_number := re.search(pattern, line): + # Memorize whether we saw a larger version number, implying that this is + # a hotfix + if Version(version_number.group()) > Version(version): + last_version_index = ind + # Add the already existing line + modified_lines.append(line) + + if "Stable" in line: + stable_index = ind + # We never found a larger number than the current, so we just insert after stable + index = last_version_index + 1 if last_version_index != -1 else stable_index + 1 + modified_lines.insert(index, new_line) + with file.open(mode="w") as f: + f.writelines(modified_lines) + + +def adjust_version_to_html(version: str) -> None: + """Adjust the shown version in the HTML files. + + This method includes the current version in the sidebar of all HTML files and + additionally adds a banner warning when the documentation is not ``stable``. + + Args: + version: The version that should be injected into the sidebar. + """ + prefix = '
  • ' + html_class = "reference external" + link = "https://avhopp.github.io/baybe_dev/versions" + new_line = ( + f'{prefix}Version: {version}
    • ' + ) + link_to_stable = 'stable' + # The content of the announcement that might be added. + announcement = ( + f"You are not viewing the documentation of the {link_to_stable} version." + ) + # Actual HTML code that will be inserted + announcement_html = ( + """
    \n""" + """ \n""" + """
    \n""" + ) + add_announcement = version != "stable" + path = Path(version) + if path.exists(): + # Recursively check all HTML files + for file in path.rglob("*.html"): + modified_lines = [] + with file.open(mode="r") as f: + lines = f.readlines() + for line in lines: + # Check if we need to add the announcement + if add_announcement: + # Add announcement at correct position + if line.strip() == '
    ': + modified_lines.insert(-2, announcement_html) + if "Versions" in line: + modified_lines.append(new_line) + else: + modified_lines.append(line) + with file.open(mode="w") as f: + f.writelines(modified_lines) + + +def check_for_hotfix(tags: list[str], version: str): + """Check whether the current build corresponds to a hotfix.""" + split_tags = tags.split("\n") + split_tags.sort(key=Version) + print(Version(version) < Version(tags[-1]), end="") + + +if __name__ == "__main__": + chosen_method = sys.argv[1] + version = sys.argv[2] + if chosen_method == "selector_page": + add_version_to_selector_page(version) + elif chosen_method == "html": + adjust_version_to_html(version) + elif chosen_method == "hotfix": + check_for_hotfix(tags=sys.argv[3], version=version) + else: + print(f"Invalid arguments {sys.argv} were chosen!") From 045fced436702bb5854e8032bf9774d55faf1861 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 8 Aug 2024 09:49:45 +0200 Subject: [PATCH 14/17] Fix capitalization error --- docs/scripts/utils.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scripts/utils.py b/docs/scripts/utils.py index 849c75cb6..06e722633 100644 --- a/docs/scripts/utils.py +++ b/docs/scripts/utils.py @@ -64,7 +64,7 @@ def add_version_to_selector_page(version: str) -> None: modified_lines = [] # Regular expression pattern to match the version number in the format X.Y.Z pattern = r"\b\d+\.\d+\.\d+\b" - # Indices for memorizing the index of the line containing "Stable" and the last + # Indices for memorizing the index of the line containing "stable" and the last # version that was larger than the one to be inserted stable_index = -1 last_version_index = -1 @@ -80,7 +80,7 @@ def add_version_to_selector_page(version: str) -> None: # Add the already existing line modified_lines.append(line) - if "Stable" in line: + if "stable" in line: stable_index = ind # We never found a larger number than the current, so we just insert after stable index = last_version_index + 1 if last_version_index != -1 else stable_index + 1 From 16cc0e4f6b8b07bc55a456d00fbb22db8b17c6e5 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 8 Aug 2024 13:19:49 +0200 Subject: [PATCH 15/17] Fix substring for finding stable --- docs/scripts/utils.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/scripts/utils.py b/docs/scripts/utils.py index 06e722633..5b583a2b9 100644 --- a/docs/scripts/utils.py +++ b/docs/scripts/utils.py @@ -80,7 +80,8 @@ def add_version_to_selector_page(version: str) -> None: # Add the already existing line modified_lines.append(line) - if "stable" in line: + # Slightly weird string since the word "stable" appears is other places + if "stable" in line: stable_index = ind # We never found a larger number than the current, so we just insert after stable index = last_version_index + 1 if last_version_index != -1 else stable_index + 1 From c68100dc19dbb961b76c0a48a70a12a5178b7bea Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 8 Aug 2024 14:25:50 +0200 Subject: [PATCH 16/17] Reset last_version_index --- docs/scripts/utils.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/scripts/utils.py b/docs/scripts/utils.py index 5b583a2b9..b26914ffc 100644 --- a/docs/scripts/utils.py +++ b/docs/scripts/utils.py @@ -71,6 +71,11 @@ def add_version_to_selector_page(version: str) -> None: with file.open(mode="r") as f: lines = f.readlines() for ind, line in enumerate(lines): + # We might find strings that look like version numbers without wanting to + # We thus need to potentially reset `last_version_index` + if "

    Available versions

    " in line: + last_version_index = -1 + # Search for the version number in the current line if version_number := re.search(pattern, line): # Memorize whether we saw a larger version number, implying that this is From 22ad8d20d946d2313db9f3ef7b283b6d36529db0 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Fri, 9 Aug 2024 14:52:59 +0200 Subject: [PATCH 17/17] Fix error in Hotfix calculation --- docs/scripts/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scripts/utils.py b/docs/scripts/utils.py index b26914ffc..cc250d943 100644 --- a/docs/scripts/utils.py +++ b/docs/scripts/utils.py @@ -149,7 +149,7 @@ def check_for_hotfix(tags: list[str], version: str): """Check whether the current build corresponds to a hotfix.""" split_tags = tags.split("\n") split_tags.sort(key=Version) - print(Version(version) < Version(tags[-1]), end="") + print(Version(version) < Version(split_tags[-1]), end="") if __name__ == "__main__":