[doc] Added support for multiversion documentation

- [GH Action] Documentation is now published as artifact for easy preview
- [GH Action] Documentation is now deployed in a subdirectory
- [conf.py] Added version switcher to switch between different doc versions

.github/workflows/documentation.yml

@@ -2,30 +2,56 @@ name: Documentation build
 
 on:  
   push:
-    branches:
-      - support/v5.13
-  release:
-    types:
-      - released
-      - unpublished
-      - deleted
 
+  # release:
+  #   types:
+  #     - released
+  #     - unpublished
+  #     - deleted
 jobs:
   documentation-build:
     runs-on: ubuntu-latest
 
     steps:
+    - name: Get current branch name
+      id: branch
+      run: |
+        # Get the branch name
+        branch=$(echo ${GITHUB_REF#refs/heads/})
+
+        # if the branch is a support/ branch, then set the doc_version
+        if [[ $branch == support/* ]]; then
+          echo "doc_version=$(echo ${branch#support/})" >> $GITHUB_ENV
+          echo "publish_dir=$(echo ${branch#support/})" >> $GITHUB_ENV
+          echo "publish_doc=true" >> $GITHUB_ENV
+        elif [[ $branch == master ]]; then
+          echo "doc_version=v999.0" >> $GITHUB_ENV
+          echo "publish_dir=latest" >> $GITHUB_ENV
+          echo "publish_doc=true" >> $GITHUB_ENV
+        else
+          echo "publish_doc=false" >> $GITHUB_ENV
+        fi
+
     - name: Install Dependencies
       run: |
         sudo apt update
         sudo apt-get install ninja-build doxygen graphviz libprotobuf-dev libprotoc-dev protobuf-compiler libhdf5-dev
 
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
-        submodules:  'true'
+        submodules:  'false'
         fetch-depth: 0
-        ref: 'support/v5.13'
+
+    - name: Update / download Submodules (selected ones)
+      run: |
+        cd $GITHUB_WORKSPACE
+        git submodule init
+        git submodule deinit thirdparty/curl/curl
+        git submodule deinit thirdparty/gtest/googletest
+        git submodule deinit thirdparty/hdf5/hdf5
+        git submodule deinit thirdparty/protobuf/protobuf
+        git submodule update
         
     - name: Install Python requirements
       shell: bash
@@ -67,7 +93,7 @@ jobs:
         -DECAL_THIRDPARTY_BUILD_TINYXML2=ON \
         -DECAL_THIRDPARTY_BUILD_FINEFTP=ON \
         -DECAL_THIRDPARTY_BUILD_CURL=OFF \
-        -DECAL_THIRDPARTY_BUILD_GTEST=ON \
+        -DECAL_THIRDPARTY_BUILD_GTEST=OFF \
         -DECAL_THIRDPARTY_BUILD_HDF5=OFF \
         -DECAL_THIRDPARTY_BUILD_RECYCLE=ON \
         -DECAL_THIRDPARTY_BUILD_TCP_PUBSUB=ON \
@@ -84,12 +110,26 @@ jobs:
     - name: Build Documentation
       env:
         ECAL_GH_API_KEY: ${{ secrets.GITHUB_TOKEN }}
+        ECAL_DOC_VERSION: ${{ env.doc_version }}
       run: cmake --build . --parallel --config Release --target documentation_sphinx
       working-directory: ${{ runner.workspace }}/_build
 
+    - name: Zip Documentation
+      run: |
+        cd ${{ runner.workspace }}/_build/doc/html
+        zip -r ${{ runner.workspace }}/_build/doc/html.zip .
+
+    - name: Upload Documentation as Artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: ${{ runner.workspace }}/_build/doc/html.zip
+
     - name: Deploy Documentation
       uses: peaceiris/actions-gh-pages@v3
       with:
         publish_branch: gh-pages
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ${{ runner.workspace }}/_build/doc/html
+        destination_dir: ${{ env.publish_dir }}
+      if: env.publish_doc == 'true'

doc/rst/conf.py

@@ -77,10 +77,16 @@
 #author = u'Continental'
 
 # The short X.Y version
-version = u''
+# version = u''
 # The full version, including alpha/beta/rc tags
-release = u''
 
+# Get release version from ECAL_DOC_VERSION environment variable
+ecal_doc_version = os.getenv("ECAL_DOC_VERSION")
+
+if not ecal_doc_version:
+    ecal_doc_version = ""
+
+release = ecal_doc_version
 
 # -- General configuration ---------------------------------------------------
 
@@ -210,6 +216,23 @@
     "extra_navbar": "", # => Remove the default text
     "footer_start": ["footer.html"],
     "extra_footer": '',
+
+    # Add version switcher to choose between different versions of the documentation
+    "switcher": {
+        "json_url": "https://eclipse-ecal.github.io/ecal/switcher.json",
+        "version_match": ecal_doc_version,
+    },
+
+     # Set to check_switcher false to allow offline builds
+    "check_switcher": False,
+
+    # Enable a banner telling the user that they look at an outdated version of the documentation
+    "show_version_warning_banner": True,
+}
+
+html_sidebars = {
+    # Add the version switchter to the sidebar
+    "**": ["navbar-logo", "icon-links", "version-switcher", "search-field", "sbt-sidebar-nav.html"]
 }
 
 # -- Options for HTMLHelp output ---------------------------------------------