Merge pull request #41 from AVHopp/docs/multi_version

Docs/multi version

.github/workflows/docs.yml

@@ -1,20 +1,14 @@
 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: ''
+  workflow_dispatch:  # Allow manually triggering the workflow
+
 
 concurrency:
   group: ${{ github.workflow }}
@@ -24,35 +18,77 @@ 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: 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]"
+            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: Create numbered version
+        run: |
+            FOLDER=${{github.event.release.tag_name}}
+            mkdir ./$FOLDER
+            cp -r docs/build/* ./$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
+              rm -rf stable
+            fi
+            mkdir ./stable
+            cp -rv docs/build/* ./stable
+            python utils.py html stable
+            git add -f stable
+      - 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

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

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": LIGHT_BLUE,
+        "color-announcement-text": LIGHT_GRAY,
     },
     # 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": LIGHT_BLUE,
+        "color-announcement-text": LIGHT_GRAY,
     },
     # Logos. Location is relative to _static folder.
     "light_logo": "logo1.svg",  # Logo for light mode

docs/index.md

@@ -1,3 +1,10 @@
+```{toctree}
+:titlesonly:
+:hidden:
+
+Versions <https://avhopp.github.io/baybe_dev/versions>
+```
+
 ```{toctree}
 :maxdepth: 2
 :titlesonly:

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,120 @@ 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}<li><a href="
+        f'"https://avhopp.github.io/baybe_dev/{version}/">{version}'
+        "</a></li>\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):
+            # We might find strings that look like version numbers without wanting to
+            # We thus need to potentially reset `last_version_index`
+            if "<h1>Available versions</h1>" 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
+                # a hotfix
+                if Version(version_number.group()) > Version(version):
+                    last_version_index = ind
+            # Add the already existing line
+            modified_lines.append(line)
+
+            # Slightly weird string since the word "stable" appears is other places
+            if "stable</a></li>" 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 = '<li class="toctree-l1">'
+    html_class = "reference external"
+    link = "https://avhopp.github.io/baybe_dev/versions"
+    new_line = (
+        f'{prefix}<a class={html_class} href="{link}">Version: {version}</a></li>'
+    )
+    link_to_stable = '<a href="https://avhopp.github.io/baybe_dev/stable">stable</a>'
+    # 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 = (
+        """<div class="announcement">\n"""
+        """    <aside class="announcement-content">\n"""
+        f"""        {announcement}\n"""
+        """    </aside>\n"""
+        """</div>\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() == '<div class="page">':
+                            modified_lines.insert(-2, announcement_html)
+                    if "Versions</a></li>" 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(split_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!")