CASSJAVA-109, CASSJAVA-117: Manual and API References after donation, Build CI for Java Driver Doc:

.github/workflows/publish-docs-gp-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

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™.
 
 ## 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
 

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

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;
    */

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) {

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.

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)

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

manual/core/README.md

@@ -30,7 +30,7 @@ following coordinates:
 </dependency>
 ```
 
-(For more details on setting up your build tool, see the [integration](integration/) page.)
+(For more details on setting up your build tool, see the [integration](integration/README.md) page.)
 
 ### Quick start
 
@@ -69,14 +69,14 @@ variants that return a `CompletionStage`).
 
 [CqlSession#builder()] provides a fluent API to create an instance programmatically. Most of the
 customization is done through the driver configuration (refer to the
-[corresponding section](configuration/) of this manual for full details).
+[corresponding section](configuration/README.md) of this manual for full details).
 
-We recommend that you take a look at the [reference configuration](configuration/reference/) for the
+We recommend that you take a look at the [reference configuration](configuration/reference/README.md) for the
 list of available options, and cross-reference with the sub-sections in this manual for more
 explanations.
 
 By default, `CqlSession.builder().build()` fails immediately if the cluster is not available. If you
-want to retry instead, you can set the [reconnect-on-init](reconnection/#at-init-time) option in the
+want to retry instead, you can set the [reconnect-on-init](reconnection/README.md#at-init-time) option in the
 configuration.
 
 ##### Contact points
@@ -91,7 +91,7 @@ This is fine for a quick start on a developer workstation, but you'll quickly wa
 specific addresses. There are two ways to do this:
 
 * via [SessionBuilder.addContactPoint()] or [SessionBuilder.addContactPoints()];
-* in the [configuration](configuration/) via the `basic.contact-points` option.
+* in the [configuration](configuration/README.md) via the `basic.contact-points` option.
 
 As soon as there are explicit contact points, you also need to provide the name of the local
 datacenter. All contact points must belong to it (as reported in their system tables:
@@ -123,7 +123,7 @@ datastax-java-driver {
 ```
 
 For more details about the local datacenter, refer to the [load balancing
-policy](load_balancing/#local-only) section.
+policy](load_balancing/README.md#datacenter-locality) section.
 
 ##### Keyspace
 
@@ -135,7 +135,7 @@ session.execute("SELECT * FROM my_keyspace.my_table WHERE id = 1");
 ```
 
 You can also specify a keyspace at construction time, either through the
-[configuration](configuration/):
+[configuration](configuration/README.md):
 
 ```
 datastax-java-driver {
@@ -203,7 +203,7 @@ ResultSet rs = session.execute("SELECT release_version FROM system.local");
 ```
 
 As shown here, the simplest form is to pass a query string directly. You can also pass a
-[Statement](statements/) instance.
+[Statement](statements/README.md) instance.
 
 #### Processing rows
 
@@ -218,7 +218,7 @@ for (Row row : rs) {
 
 This will return **all results** without limit (even though the driver might use multiple queries in
 the background). To handle large result sets, you might want to use a `LIMIT` clause in your CQL
-query, or use one of the techniques described in the [paging](paging/) documentation.
+query, or use one of the techniques described in the [paging](paging/README.md) documentation.
 
 When you know that there is only one row (or are only interested in the first one), the driver
 provides a convenience method:
@@ -257,10 +257,10 @@ See [AccessibleByName] for an explanation of the conversion rules.
 | blob               | getByteBuffer  | java.nio.ByteBuffer  |                                   |
 | boolean            | getBoolean     | boolean              |                                   |
 | counter            | getLong        | long                 |                                   |
-| date               | getLocalDate   | java.time.LocalDate  | [Temporal types](temporal_types/) |
+| date               | getLocalDate   | java.time.LocalDate  | [Temporal types](temporal_types/README.md) |
 | decimal            | getBigDecimal  | java.math.BigDecimal |                                   |
 | double             | getDouble      | double               |                                   |
-| duration           | getCqlDuration | [CqlDuration]        | [Temporal types](temporal_types/) |
+| duration           | getCqlDuration | [CqlDuration]        | [Temporal types](temporal_types/README.md) |
 | float              | getFloat       | float                |                                   |
 | inet               | getInetAddress | java.net.InetAddress |                                   |
 | int                | getInt         | int                  |                                   |
@@ -269,27 +269,27 @@ See [AccessibleByName] for an explanation of the conversion rules.
 | set                | getSet         | java.util.Set<T>     |                                   |
 | smallint           | getShort       | short                |                                   |
 | text               | getString      | java.lang.String     |                                   |
-| time               | getLocalTime   | java.time.LocalTime  | [Temporal types](temporal_types/) |
-| timestamp          | getInstant     | java.time.Instant    | [Temporal types](temporal_types/) |
+| time               | getLocalTime   | java.time.LocalTime  | [Temporal types](temporal_types/README.md) |
+| timestamp          | getInstant     | java.time.Instant    | [Temporal types](temporal_types/README.md) |
 | timeuuid           | getUuid        | java.util.UUID       |                                   |
 | tinyint            | getByte        | byte                 |                                   |
-| tuple              | getTupleValue  | [TupleValue]         | [Tuples](tuples/)                 |
-| user-defined types | getUDTValue    | [UDTValue]           | [User-defined types](udts/)       |
+| tuple              | getTupleValue  | [TupleValue]         | [Tuples](tuples/README.md)                 |
+| user-defined types | getUDTValue    | [UDTValue]           | [User-defined types](udts/README.md)       |
 | uuid               | getUuid        | java.util.UUID       |                                   |
 | varchar            | getString      | java.lang.String     |                                   |
 | varint             | getBigInteger  | java.math.BigInteger |                                   |
-| vector             | getVector      | [CqlVector]          | [Custom Codecs](custom_codecs/)   |
+| vector             | getVector      | [CqlVector]          | [Custom Codecs](custom_codecs/README.md)   |
 
 Sometimes the driver has to infer a CQL type from a Java type (for example when handling the values 
-of [simple statements](statements/simple/)); for those that have multiple CQL equivalents, it makes
+of [simple statements](statements/simple/README.md)); for those that have multiple CQL equivalents, it makes
 the following choices:
 
 * `java.lang.String`: `text`
 * `long`: `bigint`
 * `java.util.UUID`: `uuid`
 
 In addition to these default mappings, you can register your own types with
-[custom codecs](custom_codecs/).
+[custom codecs](custom_codecs/README.md).
 
 ##### Primitive types