From eb3bfb7bc35818be67b9ad2d0e93de86a8f3680e Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Wed, 17 Jul 2024 16:11:19 +0200 Subject: [PATCH 1/9] 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 b90b0d8505f90632d71706b72d5d6833608f8081 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 14 May 2024 17:40:01 +0200 Subject: [PATCH 2/9] 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 1ae69d6ed..15147fefd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,6 +34,7 @@ License User Guide Examples +Versions ``` # Indices and Tables From 5db2826f3171fe28345db42bc5247bbab5ca9c1f Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 18 Jul 2024 13:54:33 +0200 Subject: [PATCH 3/9] 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 e702420b5173c70119f089140eefabbd6cb653db Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Thu, 18 Jul 2024 14:28:21 +0200 Subject: [PATCH 4/9] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30a45fb99..13173a1c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `BasicKernel` and `CompositeKernel` base classes - Activated `pre-commit.ci` with auto-update - User guide for active learning +- Multi-version documentation ### Changed - Passing an `Objective` to `Campaign` is now optional From 0f331a231ea5e3f0ff47e0269df8b62b3bd4aa61 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Sun, 21 Jul 2024 16:08:23 +0200 Subject: [PATCH 5/9] 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 b5bc77d6f573001a9239ff1e055d226a51d7e4e5 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 09:44:23 +0200 Subject: [PATCH 6/9] Make versions a section in the sidebar --- docs/index.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/index.md b/docs/index.md index 15147fefd..57089afa4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,6 +34,13 @@ License User Guide Examples +``` + +```{toctree} +:titlesonly: +:caption: Versions +:hidden: + Versions ``` From 114a05ec6a2323367ae5304778b6f5eaafae7357 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:00:30 +0200 Subject: [PATCH 7/9] 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 16c976236..d1482eec8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -185,6 +185,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": { @@ -219,6 +222,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 c81383bc9c5309146d4214ac6fa5b14d82ee43d7 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:35:50 +0200 Subject: [PATCH 8/9] 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 3a78c0f4c8ac7f1e1139e6087318ca7ffaf8aa47 Mon Sep 17 00:00:00 2001 From: "Alexander V. Hopp" Date: Tue, 23 Jul 2024 10:37:52 +0200 Subject: [PATCH 9/9] 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"""