Documentation page and GitHub action

Author: lukasz-antoniak

.github/workflows/build-docs-gh-pages.yml

@@ -0,0 +1,105 @@
+name: publish-docs-gp-pages
+
+on:
+# TODO: Can we trigger action manually?
+#  push:
+#    branches:
+#      - 4.x
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      # 1. Checkout doc branch
+      - name: Checkout current branch
+        uses: actions/checkout@v4
+        with:
+          path: java-driver
+
+      # 2. Java 8
+      - name: Set up Java 8
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "8"
+          cache: maven
+
+      # 3. Python 3.10.19 + MkDocs + plugins
+      - name: Set up Python 3.10.19
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10.19"
+
+      - name: Install MkDocs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            mkdocs \
+            mkdocs-material \
+            mkdocs-awesome-pages-plugin \
+            mkdocs-macros-plugin \
+            mike
+
+      # 4. Build docs via build-doc.sh
+      - name: Build documentation
+        working-directory: java-driver
+        run: |
+          chmod +x ./build-doc.sh
+          ./build-doc.sh
+
+      # 5. Checkout gh-pages branch
+      - name: Checkout GH pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      - name: Copy and version documentation
+        working-directory: gh-pages
+        run: |
+          git config --global user.email "gha@cassandra.apache.org"
+          git config --global user.name "GHA for Apache Cassandra Website"
+
+          cd ../java-driver
+          # lookup current project version
+          release_version=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout | cut -d- -f1)
+          # update links to contain version prefix
+          mike deploy --update-aliases $release_version
+          # copy documentation web page folder
+          cd ../gh-pages
+          cp -r ../java-driver/docs ./
+          rm -rf $release_version
+          mv docs $release_version
+
+          # update latest symlink
+          rm latest
+          ln -s $release_version latest
+
+          # remove latest tag
+          sed -i 's/\"latest\"//g' versions.json
+          # remove already present line if exists
+          sed -i '/'"$release_version"'/d' versions.json
+          # insert new version at the beginning
+          sed -i '2s/^/  { "version": "'"$release_version"'", "title": "'"$release_version"'", "aliases": ["latest"] },\'$'\n/g' versions.json
+
+          echo "release_version=$release_version" >> "$GITHUB_ENV"
+
+      - name: Commit and push documentation
+        working-directory: gh-pages
+        run: |
+          git config --global user.email "gha@cassandra.apache.org"
+          git config --global user.name "GHA for Apache Cassandra Website"
+
+          git add .
+
+          if git diff --cached --quiet; then
+            echo "No changes to push to gh-pages"
+            exit 0
+          fi
+
+          git commit -m "Update generated docs for release ${release_version}"
+          git push origin gh-pages

.github/workflows/publish-docs-gp-pages.yml

@@ -9,14 +9,12 @@ site_dir: docs
 
 theme:
   name: material
-  palette:
-    - scheme: default
-      primary: blue
-      accent: blue
+  logo: faq/logo.png
+  favicon: faq/favicon.ico
   features:
     - navigation.tabs
-    - navigation.sections
     - navigation.top
+    - navigation.path
     - search.highlight
     - search.share
 
@@ -26,6 +24,7 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed
   - toc:
+      toc_depth: 1
       permalink: true
 
 nav:
@@ -39,8 +38,8 @@ nav:
       - Overview: manual/core/README.md
       - Integration: manual/core/integration/README.md
       - Configuration:
-          - Overview: manual/core/configuration/README.md
-          - Reference: manual/core/configuration/reference/README.md
+        - Overview: manual/core/configuration/README.md
+        - Reference: manual/core/configuration/reference/README.md
       - Authentication: manual/core/authentication/README.md
       - SSL: manual/core/ssl/README.md
       - Load Balancing: manual/core/load_balancing/README.md
@@ -162,3 +161,10 @@ plugins:
   - search
   - awesome-pages
   - macros
+  - mike:
+      alias_type: copy
+
+extra:
+  generator: false
+  version:
+    provider: mike