CASSJAVA-109, CASSJAVA-117: Manual and API References after donation, Build CI for Java Driver Doc:#2063
CASSJAVA-109, CASSJAVA-117: Manual and API References after donation, Build CI for Java Driver Doc:#2063SiyaoIsHiding wants to merge 7 commits intoapache:4.xfrom
Conversation
| </dependency> | ||
| <dependency> | ||
| <groupId>com.github.spotbugs</groupId> | ||
| <artifactId>spotbugs-annotations</artifactId> |
There was a problem hiding this comment.
Need to figure out how come previously we didn't need to add those annotation dependencies?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
| run: | | ||
| cp -r ../java-driver/docs ./docs/latest | ||
| mkdocs build | ||
| cp -r ./out/. . # because the index.html has to be in the root folder |
There was a problem hiding this comment.
mv instead of cp
| mvn clean install -DskipTests # or guava-shaded can not be found | ||
| # mvn javadoc:javadoc -pl core,query-builder,mapper-runtime | ||
| mvn javadoc:aggregate | ||
|
|
There was a problem hiding this comment.
add the sym links here instead of committing them
Documentation page and GitHub action
absurdfarce
left a comment
absurdfarce
left a comment
There was a problem hiding this comment.
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!
| * 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> |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
| </dependency> | ||
| <dependency> | ||
| <groupId>com.github.spotbugs</groupId> | ||
| <artifactId>spotbugs-annotations</artifactId> |
There was a problem hiding this comment.
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.
3 participants
Several things this PR do:
docsof symbol links as mkdocs' working directory, and the build script "./build-doc.sh"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-pages-stagingon 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)