CASSJAVA-109, CASSJAVA-117: Manual and API References after donation, Build CI for Java Driver Doc: by SiyaoIsHiding · Pull Request #2063 · apache/cassandra-java-driver

SiyaoIsHiding · 2025-11-20T01:07:20Z

Several things this PR do:

Fix the broken Java doc and broken links in the existing manual
mkdocs config e..g mkdocs.yaml, folder docs of symbol links as mkdocs' working directory, and the build script "./build-doc.sh"
GH Action CI to upload built doc as an artifact on PR
e.g. Download the zip here. Unzip, and run this command in the root directory to preview the website: python -m http.server (with python3).
GH Action to update the branch gh-pages-staging on 4.x commit (PR merged). Example run: https://github.com/SiyaoIsHiding/java-driver/actions/runs/19521378245 (someone with write access need to create that branch first)

SiyaoIsHiding · 2025-12-09T16:43:55Z

pom.xml

+          </dependency>
+          <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs-annotations</artifactId>


Need to figure out how come previously we didn't need to add those annotation dependencies?

Hmmm, I thought this got taken out as a side effect of some other work that was done... but I can't find that change now. Perhaps more importantly it looks like these dependencies are still in 4.x and apparently have been for some time.

Ah, okay, I did find it. I was thinking of some work done for dsbulk, specifically the omnibus version updates. This comment provides the relevant context; they were removed in the transition of the Java driver to the ASF, I believe because of some licensing concerns. The relevant change is here, controlling ticket is CASSJAVA-34.

As mentioned above the dependencies are still in pom.xml and are marked as "provided" in all the submodules due to the changes in CASSJAVA-34. That's why I had to include them manually in dsbulk when we upgraded to the new driver.

Can you elaborate more on why you need them in this PR?

I met failure to run mvn javadoc:aggregate, but it seems like running mvn clean install -DskipTests beforehand resolved this problem. Removed the unnecessary dependencies

SiyaoIsHiding · 2025-12-11T18:15:50Z

.github/workflows/update-docs-staging.yml

+        run: |
+          cp -r ../java-driver/docs ./docs/latest
+          mkdocs build
+          cp -r ./out/. .      # because the index.html has to be in the root folder


mv instead of cp

SiyaoIsHiding · 2025-12-11T18:17:24Z

build-doc.sh

+mvn clean install -DskipTests # or guava-shaded can not be found
+# mvn javadoc:javadoc -pl core,query-builder,mapper-runtime
+mvn javadoc:aggregate
+


add the sym links here instead of committing them

Documentation page and GitHub action

Fix ToC

absurdfarce

Looks pretty good to me overall @SiyaoIsHiding! A couple small things I think we need to take a look at but overall I'm pretty happy with where this is headed!

absurdfarce · 2026-03-31T22:00:27Z

core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java

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


Perhaps not related to this change but this link... offers very little information about what a prefix block is. The text literally reads "Returns whether the address range has a prefix length and includes the block of values for its prefix length.", which isn't super-descriptive.

We'd prolly be better pointing users at something from the manual, something like https://seancfoley.github.io/IPAddress/ipaddress.html#parsing-addresses-with-prefix-length.

Separate point: pointing at latest is always tricky because that can change underneath you. Better to point at a specific version or tag; that way the content stands a much better chance of remaining fixed.

Sweet, I think this will offer better guidance to users. I'll admit that there is part of me which is tempted to inline the definition of prefix block into this comment... but we don't have to take that step now. I'm happy with the way it stands now; it's a definite improvement over what was there originally.

absurdfarce · 2026-03-31T22:10:42Z

manual/core/non_blocking/README.md

+See the section about [throttling](../throttling/README.md) for details about these components. Again, they 
+use locks internally, and depending on how many requests are being executed in parallel, the thread
+contention on these locks can be high: in short, if your application enforces strict lock-freedom, 
+then these components should not be used.


Looks like perhaps there was a missed deletion here; the content of the paragraph that's been added here is identical to the what's above and when I look at this content on Github it reads oddly.

Nice! After cleanup this looks exactly like what I'd expect. Looks much better in Github's rendering as well.

absurdfarce · 2026-03-31T23:19:38Z

pom.xml

+          </dependency>
+          <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs-annotations</artifactId>


Hmmm, I thought this got taken out as a side effect of some other work that was done... but I can't find that change now. Perhaps more importantly it looks like these dependencies are still in 4.x and apparently have been for some time.

# Conflicts: # README.md # manual/core/graalvm/README.md

SiyaoIsHiding · 2026-04-08T01:40:07Z

@lukasz-antoniak , confirming, we don't need the branch gh-pages-staging anymore, because the code will publish doc on new releases automatically onto gh-pages, am I right?

absurdfarce

I'm good with where this is at now. Let's get the following steps taken care of and then we should be ready to go:

Sort out the gh-pages-staging question. I agree with @SiyaoIsHiding that there's no obvious need for a branch with this name (since the publishing process spelled out here only relies on gh-pages) but I could easily have missed something.
Fix the conflicts
Squash the commits

Once those items are taken care of (and we get another 👍 ) we should be all set to go!

SiyaoIsHiding marked this pull request as ready for review November 20, 2025 01:16

SiyaoIsHiding force-pushed the doc branch from 5b5e9fb to 88679d3 Compare November 20, 2025 03:11

squashed

3fb5196

SiyaoIsHiding force-pushed the doc branch from 88679d3 to 3fb5196 Compare November 20, 2025 03:16

SiyaoIsHiding mentioned this pull request Nov 25, 2025

Update manual and API links to newly-published docs #2065

Draft

SiyaoIsHiding commented Dec 9, 2025

View reviewed changes

SiyaoIsHiding commented Dec 11, 2025

View reviewed changes

lukasz-antoniak and others added 6 commits December 17, 2025 09:40

Documentation page and GitHub action

505a9ad

Merge pull request #8 from lukasz-antoniak/doc-5

97a5eb3

Documentation page and GitHub action

Fix ToC

fda3d8d

Group Manual > Core topics

622c42c

GH Pages branch

aae294b

Merge pull request #9 from lukasz-antoniak/doc-5

6c60467

Fix ToC

absurdfarce requested changes Mar 31, 2026

View reviewed changes

SiyaoIsHiding added 4 commits April 2, 2026 20:17

remove unnecessary dependencies

e3842d7

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

a197552

address feedback

7435edb

Merge branch '4.x' of github.com:datastax/java-driver into doc

b2196d0

# Conflicts: # README.md # manual/core/graalvm/README.md

SiyaoIsHiding requested a review from absurdfarce April 8, 2026 01:40

absurdfarce approved these changes Apr 8, 2026

View reviewed changes

Conversation

SiyaoIsHiding commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

absurdfarce Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

absurdfarce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SiyaoIsHiding commented Apr 8, 2026

Uh oh!

absurdfarce left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SiyaoIsHiding commented Nov 20, 2025 •

edited

Loading

absurdfarce Mar 31, 2026 •

edited

Loading