separate documentation for different versions

Fixes #36
OleksandrKvl · May 7, 2024 · be1a8f6 · be1a8f6
1 parent 76e207f
commit be1a8f6
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 42 deletions.
diff --git a/.github/workflows/doxygen-gh-pages.yml b/.github/workflows/doxygen-gh-pages.yml
@@ -1,54 +1,123 @@
-name: Doxygen
+name: Documentation workflow
 
 permissions:
   contents: write
 
+env:
+  BUILD_DIR: ${{github.workspace}}/build
+  SELECTOR_FILE_NAME: version_selector.html
+  SELECTOR_ID: versionSelector
+  GIT_USER_NAME: 'Oleksandr Koval'
+  GIT_USER_EMAIL: 'OleksandrKvl@users.noreply.github.com'
+
 on:
+  # to update docs/git-main
   push:
     branches:
       - main
-  pull_request:
-    branches:
-      - main
+  # to publish docs/<release-version>
+  release:
+    types: [released]
 
 jobs:
-  build:
-    # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
-    # You can convert this to a matrix build if you need cross-platform coverage.
-    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
+  publish-docs:
     runs-on: ubuntu-22.04
 
     steps:
-    - uses: actions/checkout@v3
-
-    - name: Install deps
-      run:   |
-              sudo apt install -y cmake
-              sudo apt install -y wget
-              wget -nv https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz
-              tar -xzf doxygen-1.10.0.linux.bin.tar.gz
-              echo "$(pwd)/doxygen-1.10.0/bin" >> $GITHUB_PATH
-
-    - name: CMake configuration
-      run:  |
-            cmake -B ${{github.workspace}}/build \
-                  -D CMAKE_C_COMPILER=/usr/bin/gcc-11 \
-                  -D CMAKE_CXX_COMPILER=/usr/bin/g++-11 \
-                  -D SBEPP_BUILD_SBEPPC=OFF \
-                  -D SBEPP_BUILD_DOCS=ON
-
-    - name: CMake build
-      run:  |
-            cmake --build ${{github.workspace}}/build \
-                  --target doc
-
-    - name: Moving Files
-      run: |
-        mv ${{github.workspace}}/build/doc/html ./doc/html
-
-    - name: Deploy to Github Pages
-      uses: peaceiris/actions-gh-pages@v3
-
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./doc/html
+      - uses: actions/checkout@v4
+
+      - name: Install deps
+        shell: bash
+        run:   |
+                sudo apt install -y cmake
+                sudo apt install -y wget
+                wget -nv https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz
+                tar -xzf doxygen-1.10.0.linux.bin.tar.gz
+                echo "$(pwd)/doxygen-1.10.0/bin" >> $GITHUB_PATH
+
+      - name: CMake configure
+        run:  cmake -B $BUILD_DIR
+
+      - name: CMake build
+        run:  cmake --build $BUILD_DIR --target doc
+
+      - name: Get docs version
+        id: get-docs-version
+        run: |
+          subdir=$(basename $(find $BUILD_DIR/doc/docs -mindepth 1 -maxdepth 1 -type d | head -n 1))
+          echo "version=$subdir" >> $GITHUB_OUTPUT
+
+      - name: Update redirect HTML
+        if: github.event_name == 'release'
+        run: |
+          mkdir $BUILD_DIR/doc/docs/redirect
+          cat << EOF > $BUILD_DIR/doc/docs/redirect/index.html
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+              <meta charset="UTF-8">
+              <meta http-equiv="refresh" content="0; url=${{ steps.get-docs-version.outputs.version }}/index.html">
+              <title>Redirecting...</title>
+          </head>
+          <body>
+              <p>If you are not redirected automatically, <a href="${{ steps.get-docs-version.outputs.version }}/index.html">click here</a>.</p>
+          </body>
+          </html>
+          EOF
+
+      - name: Deploy release docs
+        if: github.event_name == 'release'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.BUILD_DIR }}/doc/docs/${{ steps.get-docs-version.outputs.version }}
+          destination_dir: ${{ steps.get-docs-version.outputs.version }}
+
+      - name: Deploy redirect page
+        if: github.event_name == 'release'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.BUILD_DIR }}/doc/docs/redirect
+          keep_files: true
+
+      - name: Deploy git-main docs
+        if: github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ env.BUILD_DIR }}/doc/docs/${{ steps.get-docs-version.outputs.version }}
+          destination_dir: git-main
+
+      # Update version_selector.html
+      - name: Pull gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+
+      - name: Discover versions
+        run: |
+          # Enumerate directories and store them in a variable
+          dirs=$(find . -mindepth 1 -maxdepth 1 -type d | sort -rV)
+      
+          # Create HTML
+          echo '<select id="$SELECTOR_ID">' > $SELECTOR_FILE_NAME
+          for dir in $dirs; do
+              if [[ "$(basename "$dir")" != .* ]]; then
+                  version=$(basename "$dir")
+                  echo "    <option value=\"$version\">$version</option>" >> $SELECTOR_FILE_NAME
+              fi
+          done
+          echo '</select>' >> $SELECTOR_FILE_NAME
+
+      - name: Push selector
+        run: |
+          git config --global user.name $GIT_USER_NAME
+          git config --global user.email $GIT_USER_EMAIL
+          if [[ -n "$(git diff --exit-code $SELECTOR_FILE_NAME)" ]]; then
+            git add $SELECTOR_FILE_NAME
+            git commit -m "Update version selector"
+            git push origin gh-pages
+          else
+            echo "$SELECTOR_FILE_NAME has not been changed. Skipping push."
+          fi
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -27,6 +27,7 @@ set(DOXYGEN_HTML_EXTRA_FILES
     "doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js"
     "doxygen-awesome-css/doxygen-awesome-paragraph-link.js"
     "doxygen-awesome-css/doxygen-awesome-interactive-toc.js"
+    "version_selector_handler.js"
 )
 set(DOXYGEN_HTML_COLORSTYLE "LIGHT")
 set(DOXYGEN_GENERATE_TREEVIEW "YES")
@@ -45,6 +46,8 @@ set(DOXYGEN_PREDEFINED
 )
 set(DOXYGEN_EXPAND_AS_DEFINED "SBEPP_BUILT_IN_IMPL")
 set(DOXYGEN_WARN_AS_ERROR "FAIL_ON_WARNINGS_PRINT")
+set(DOXYGEN_HTML_OUTPUT "${PROJECT_VERSION}")
+set(DOXYGEN_OUTPUT_DIRECTORY "docs")
 
 doxygen_add_docs(
     doc

diff --git a/doc/header.html b/doc/header.html
@@ -32,6 +32,8 @@
     DoxygenAwesomeParagraphLink.init()
     DoxygenAwesomeInteractiveToc.init()
 </script>
+
+<script type="text/javascript" src="$relpath^version_selector_handler.js"></script>
 </head>
 <body>
 <!--BEGIN DISABLE_INDEX-->
@@ -52,7 +54,7 @@
   <!--END PROJECT_LOGO-->
   <!--BEGIN PROJECT_NAME-->
   <td id="projectalign">
-   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber"/><!--END PROJECT_NUMBER-->
    </div>
    <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
   </td>

diff --git a/doc/version_selector_handler.js b/doc/version_selector_handler.js
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024, Oleksandr Koval
+
+$(function () {
+    $.get('/version_selector.html', function (data) {
+        // Inject version selector HTML into the page
+        $('#projectnumber').html(data);
+
+        // Event listener to handle version selection
+        document.getElementById('versionSelector').addEventListener('change', function () {
+            var selectedVersion = this.value;
+            window.location.href = '/' + selectedVersion + '/index.html';
+
+        });
+
+        // Set the selected option based on the current version
+        var currentVersion = window.location.pathname.split('/')[1];
+        $('#versionSelector').val(currentVersion);
+    });
+});