SiyaoIsHiding · SiyaoIsHiding · Nov 20, 2025
diff --git a/.github/workflows/build-docs-gh-pages.yml b/.github/workflows/build-docs-gh-pages.yml
@@ -0,0 +1,60 @@
+name: Build docs and upload ZIP
+
+on:
+  pull_request:
+    branches:
+      - 4.x
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      # 1. Checkout current branch
+      - name: Checkout current branch
+        uses: actions/checkout@v4
+
+      # 2. Java 8 (with Maven cache)
+      - name: Set up Java 8
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "8"
+          cache: maven        # <--- cache Maven deps (~/.m2/repository)
+
+      # 3. Python 3.10.19
+      - name: Set up Python 3.10.19
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10.19"
+
+      # 4. Install MkDocs dependencies
+      - name: Install MkDocs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install \
+            mkdocs \
+            mkdocs-material \
+            mkdocs-awesome-pages-plugin \
+            mkdocs-macros-plugin
+
+      # 5. Build docs via build-doc.sh
+      - name: Build documentation
+        run: |
+          chmod +x ./build-doc.sh
+          ./build-doc.sh
+
+      # 6. Upload built docs as a ZIP artifact
+      - name: Archive built documentation
+        run: |
+          zip -r docs-built.zip docs
+
+      - name: Upload built doc artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: built-docs-zip
+          path: docs-built.zip
+          retention-days: 10
diff --git a/.github/workflows/update-docs-staging.yml b/.github/workflows/update-docs-staging.yml
@@ -0,0 +1,81 @@
+name: Update gh-pages-staging on commit
+
+on:
+  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        # <--- cache Maven deps (~/.m2/repository)
+
+      # 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
+
+      # 4. Build docs via build-doc.sh
+      - name: Build documentation
+        working-directory: java-driver
+        run: |
+          chmod +x ./build-doc.sh
+          ./build-doc.sh
+
+
+      # 6. Checkout gh-pages-staging branch
+      - name: Checkout gh-pages-staging
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages-staging
+          path: gh-pages-staging
+
+      - name: Copy and Build Doc
+        working-directory: gh-pages-staging
+        run: |
+          cp -r ../java-driver/docs ./docs/latest
+          mkdocs build
+          cp -r ./out/. .      # because the index.html has to be in the root folder
+
+      - name: Commit and push to gh-pages-staging
+        working-directory: gh-pages-staging
+        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"
+          git push origin gh-pages-staging
diff --git a/README.md b/README.md
@@ -45,8 +45,8 @@ are multiple modules, all prefixed with `java-driver-`.
 Note that the query builder is now published as a separate artifact, you'll need to add the
 dependency if you plan to use it.
 
-Refer to each module's manual for more details ([core](manual/core/), [query
-builder](manual/query_builder/), [mapper](manual/mapper)).
+Refer to each module's manual for more details ([core](manual/core/README.md), [query
+builder](manual/query_builder/README.md), [mapper](manual/mapper/README.md)).
 
 [org.apache.cassandra]: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.cassandra%22
 
@@ -65,15 +65,15 @@ but DataStax does not officially support these systems.
 Java Driver 4 is **not binary compatible** with previous versions. However, most of the concepts
 remain unchanged, and the new API will look very familiar to 2.x and 3.x users.
 
-See the [upgrade guide](upgrade_guide/) for details.
+See the [upgrade guide](upgrade_guide/README.md) for details.
 
 ## Error Handling
 
 See the [Cassandra error handling done right blog](https://www.datastax.com/blog/cassandra-error-handling-done-right) for error handling with the Java Driver for Apache Cassandra&trade;.
 
 ## Useful links
 
-* [Manual](manual/)
+* [Manual](manual/README.md)
 * [API docs]
 * Bug tracking: [JIRA]
 * [Mailing list]
@@ -83,8 +83,8 @@ See the [Cassandra error handling done right blog](https://www.datastax.com/blog
 [API docs]: https://docs.datastax.com/en/drivers/java/4.17
 [JIRA]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSJAVA%20ORDER%20BY%20key%20DESC
 [Mailing list]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
-[Changelog]: changelog/
-[FAQ]: faq/
+[Changelog]: changelog/README.md
+[FAQ]: faq/README.md
 
 ## License
 

diff --git a/build-doc.sh b/build-doc.sh
@@ -0,0 +1,16 @@
+set -e
+# Set up python environment
+#pyenv local 3.10.1
+#pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-macros-plugin
+
+# In some bash/zsh environments, the locale is not set correctly, which causes mkdocs to fail.
+export LC_ALL=en_US.UTF-8
+export LANG=en_US.UTF-8
+
+# Build Javadoc
+mvn clean install -DskipTests # or guava-shaded can not be found
+# mvn javadoc:javadoc -pl core,query-builder,mapper-runtime
+mvn javadoc:aggregate
+
+# Build manual with API references
+mkdocs build -s # strict, so it fails with warning. You can also use `mkdocs serve` to preview
diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java b/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java
@@ -1022,8 +1022,8 @@ public enum DefaultDriverOption implements DriverOption {
    * }
    * </pre>
    *
-   * Note: subnets must be represented as prefix blocks, see {@link
-   * inet.ipaddr.Address#isPrefixBlock()}.
+   * Note: subnets must be represented as prefix blocks, see <a
+   * href="https://javadoc.io/doc/com.github.seancfoley/ipaddress/latest/inet/ipaddr/Address.html#isPrefixBlock--">inet.ipaddr.Address.isPrefixBlock()</a>
    *
    * <p>Value type: {@link java.util.Map Map}&#60;{@link String},{@link String}&#62;
    */

diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/data/CqlVector.java b/core/src/main/java/com/datastax/oss/driver/api/core/data/CqlVector.java
@@ -80,7 +80,7 @@ public static <V> CqlVector<V> newInstance(List<V> list) {
    * Create a new CqlVector instance from the specified string representation.
    *
    * @param str a String representation of a CqlVector
-   * @param subtypeCodec
+   * @param subtypeCodec the codec to use to parse the individual elements
    * @return a new CqlVector built from the String representation
    */
   public static <V> CqlVector<V> from(@NonNull String str, @NonNull TypeCodec<V> subtypeCodec) {

diff --git a/faq/README.md b/faq/README.md
@@ -65,7 +65,7 @@ At any rate, `CompletionStage` has a `toCompletableFuture()` method. In current
 ### Where is `DowngradingConsistencyRetryPolicy` from driver 3?
 
 **As of driver 4.10, this retry policy was made available again as a built-in alternative to the 
-default retry policy**: see the [manual](../manual/core/retries) to understand how to use it. 
+default retry policy**: see the [manual](../manual//core/retries/README.md) to understand how to use it. 
 For versions between 4.0 and 4.9 inclusive, there is no built-in equivalent of driver 3 
 `DowngradingConsistencyRetryPolicy`.
 
@@ -100,7 +100,7 @@ This ability is considered a misfeature and has been removed from driver 4.0 onw
 However, due to popular demand, cross-datacenter failover has been brought back to driver 4 in
 version 4.10.0.
 
-If you are using a driver version >= 4.10.0, read the [manual](../manual/core/loadbalancing/) to
+If you are using a driver version >= 4.10.0, read the [manual](../manual//core/load_balancing/README.md) to
 understand how to enable this feature; for driver versions < 4.10.0, this feature is simply not
 available.
 
@@ -109,7 +109,7 @@ available.
 The driver now uses Java 8's improved date and time API. CQL type `timestamp` is mapped to
 `java.time.Instant`, and the corresponding getter and setter are `getInstant` and `setInstant`.
 
-See [Temporal types](../manual/core/temporal_types/) for more details.
+See [Temporal types](../manual//core/temporal_types/README.md) for more details.
 
 ### Why do DDL queries have a higher latency than driver 3?
 
@@ -119,6 +119,6 @@ noticeably higher latency than driver 3 (about 1 second).
 This is because those queries are now *debounced*: the driver adds a short wait in an attempt to
 group multiple schema changes into a single metadata refresh. If you want to mitigate this, you can
 either adjust the debouncing settings, or group your schema updates while temporarily disabling the
-metadata; see the [performance](../manual/core/performance/#debouncing) page.
+metadata; see the [performance](../manual//core/performance/README.md#debouncing) page.
 
 This only applies to DDL queries; DML statements (`SELECT`, `INSERT`...) are not debounced.
diff --git a/manual/README.md b/manual/README.md
@@ -21,16 +21,16 @@ under the License.
 
 Driver modules:
 
-* [Core](core/): the main entry point, deals with connectivity and query execution.
-* [Query builder](query_builder/): a fluent API to create CQL queries programmatically.
-* [Mapper](mapper/): generates the boilerplate to execute queries and convert the results into
+* [Core](core/README.md): the main entry point, deals with connectivity and query execution.
+* [Query builder](query_builder/README.md): a fluent API to create CQL queries programmatically.
+* [Mapper](mapper/README.md): generates the boilerplate to execute queries and convert the results into
   application-level objects.
-* [Developer docs](developer/): explains the codebase and internal extension points for advanced
+* [Developer docs](developer/README.md): explains the codebase and internal extension points for advanced
   customization.
 
 Common topics:
 
-* [API conventions](api_conventions/)
-* [Case sensitivity](case_sensitivity/)
-* [OSGi](osgi/)
-* [Cloud](cloud/)
+* [API conventions](api_conventions/README.md)
+* [Case sensitivity](case_sensitivity/README.md)
+* [OSGi](osgi/README.md)
+* [Cloud](cloud/README.md)
diff --git a/manual/cloud/README.md b/manual/cloud/README.md
@@ -146,5 +146,5 @@ public class Main {
 [Create an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/creating-your-astra-database.html
 [Access an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html#_sharing_your_secure_connect_bundle
 [Download the secure connect bundle - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html
-[minimal project structure]: ../core/integration/#minimal-project-structure
-[driver documentation]: ../core/configuration/
+[minimal project structure]: ../core/integration/README.md#minimal-project-structure
+[driver documentation]: ../core/configuration/README.md