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

Patch by Jane He and
Łukasz Antoniak; Reviewed by Bret McGuire

Author: SiyaoIsHiding

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

README.md

@@ -43,8 +43,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
 
@@ -63,11 +63,11 @@ 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.
 
 ## Useful links
 
-* [Manual](manual/)
+* [Manual](manual/README.md)
 * [API docs]
 * Bug tracking: [JIRA]
 * [Mailing list]
@@ -77,8 +77,8 @@ See the [upgrade guide](upgrade_guide/) for details.
 [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://lists.apache.org/list.html?user@cassandra.apache.org
-[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://seancfoley.github.io/IPAddress/ipaddress.html#parsing-addresses-with-prefix-length">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.

faq/favicon.ico

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

faq/logo.png

@@ -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