Merge branch 'doc' of github.com:SiyaoIsHiding/java-driver into doc

Author: SiyaoIsHiding

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

@@ -0,0 +1,101 @@
+name: publish-docs-gh-pages
+
+on:
+  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: 2-3
       permalink: true
 
 nav:
@@ -39,49 +38,56 @@ 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
-      - Authentication: manual/core/authentication/README.md
-      - SSL: manual/core/ssl/README.md
-      - Load Balancing: manual/core/load_balancing/README.md
-      - Pooling: manual/core/pooling/README.md
-      - Reconnection: manual/core/reconnection/README.md
-      - Retries: manual/core/retries/README.md
-      - Speculative Execution: manual/core/speculative_execution/README.md
-      - Metrics: manual/core/metrics/README.md
-      - Logging: manual/core/logging/README.md
+        - Overview: manual/core/configuration/README.md
+        - Reference: manual/core/configuration/reference/README.md
+      - Connection Management:
+        - Authentication: manual/core/authentication/README.md
+        - SSL: manual/core/ssl/README.md
+        - Pooling: manual/core/pooling/README.md
+        - Load Balancing: manual/core/load_balancing/README.md
+        - Reconnection: manual/core/reconnection/README.md
+        - Address Resolution: manual/core/address_resolution/README.md
       - Statements:
         - Overview: manual/core/statements/README.md
         - Batch: manual/core/statements/batch/README.md
         - Per Query Keyspace: manual/core/statements/per_query_keyspace/README.md
         - Prepared: manual/core/statements/prepared/README.md
         - Simple: manual/core/statements/simple/README.md
-      - Paging: manual/core/paging/README.md
-      - Async Programming: manual/core/async/README.md
-      - Reactive Streams: manual/core/reactive/README.md
-      - Custom Codecs: manual/core/custom_codecs/README.md
-      - Temporal Types: manual/core/temporal_types/README.md
-      - Tuples: manual/core/tuples/README.md
-      - UDTs: manual/core/udts/README.md
-      - Compression: manual/core/compression/README.md
-      - Address Resolution: manual/core/address_resolution/README.md
-      - Request Tracker: manual/core/request_tracker/README.md
-      - Request ID: manual/core/request_id/README.md
-      - Throttling: manual/core/throttling/README.md
-      - Tracing: manual/core/tracing/README.md
-      - Performance: manual/core/performance/README.md
+      - Query Execution:
+        - Retries: manual/core/retries/README.md
+        - Idempotence: manual/core/idempotence/README.md
+        - Speculative Execution: manual/core/speculative_execution/README.md
+        - Paging: manual/core/paging/README.md
+        - Query Timestamps: manual/core/query_timestamps/README.md
+      - Advanced Types:
+        - Custom Codecs: manual/core/custom_codecs/README.md
+        - Temporal Types: manual/core/temporal_types/README.md
+        - Tuples: manual/core/tuples/README.md
+        - UDTs: manual/core/udts/README.md
+        - Detachable Types: manual/core/detachable_types/README.md
+      - Non-blocking:
+        - Overview: manual/core/non_blocking/README.md
+        - Async Programming: manual/core/async/README.md
+        - Reactive Streams: manual/core/reactive/README.md
+      - Observability:
+        - Request Tracker: manual/core/request_tracker/README.md
+        - Request ID: manual/core/request_id/README.md
+        - Metrics: manual/core/metrics/README.md
+        - Logging: manual/core/logging/README.md
+        - Tracing: manual/core/tracing/README.md
+      - Performance:
+        - Overview: manual/core/performance/README.md
+        - Throttling: manual/core/throttling/README.md
+        - Compression: manual/core/compression/README.md
       - Metadata:
         - Overview: manual/core/metadata/README.md
         - Node: manual/core/metadata/node/README.md
         - Schema: manual/core/metadata/schema/README.md
         - Token: manual/core/metadata/token/README.md
-      - Control Connection: manual/core/control_connection/README.md
-      - Native Protocol: manual/core/native_protocol/README.md
-      - Non-blocking: manual/core/non_blocking/README.md
-      - Query Timestamps: manual/core/query_timestamps/README.md
-      - Idempotence: manual/core/idempotence/README.md
-      - Detachable Types: manual/core/detachable_types/README.md
-      - DSE:
+      - Driver Internals:
+        - Control Connection: manual/core/control_connection/README.md
+        - Native Protocol: manual/core/native_protocol/README.md
+      - DataStax DSE:
         - Overview: manual/core/dse/README.md
         - Geotypes: manual/core/dse/geotypes/README.md
         - Graph:
@@ -162,3 +168,10 @@ plugins:
   - search
   - awesome-pages
   - macros
+  - mike:
+      alias_type: copy
+
+extra:
+  generator: false
+  version:
+    provider: mike