Skip to content

Commit 3fb5196

Browse files
SiyaoIsHidingSiyaoIsHiding
committed
squashed
1 parent 62eade2 commit 3fb5196

File tree

113 files changed

+913
-520
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

113 files changed

+913
-520
lines changed

‎.github/workflows/build-docs-gh-pages.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Build docs and upload ZIP
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- 4.x
7+
workflow_dispatch:
8+
9+
jobs:
10+
build-docs:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
15+
steps:
16+
# 1. Checkout current branch
17+
- name: Checkout current branch
18+
uses: actions/checkout@v4
19+
20+
# 2. Java 8 (with Maven cache)
21+
- name: Set up Java 8
22+
uses: actions/setup-java@v4
23+
with:
24+
distribution: temurin
25+
java-version: "8"
26+
cache: maven # <--- cache Maven deps (~/.m2/repository)
27+
28+
# 3. Python 3.10.19
29+
- name: Set up Python 3.10.19
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.10.19"
33+
34+
# 4. Install MkDocs dependencies
35+
- name: Install MkDocs dependencies
36+
run: |
37+
python -m pip install --upgrade pip
38+
pip install \
39+
mkdocs \
40+
mkdocs-material \
41+
mkdocs-awesome-pages-plugin \
42+
mkdocs-macros-plugin
43+
44+
# 5. Build docs via build-doc.sh
45+
- name: Build documentation
46+
run: |
47+
chmod +x ./build-doc.sh
48+
./build-doc.sh
49+
50+
# 6. Upload built docs as a ZIP artifact
51+
- name: Archive built documentation
52+
run: |
53+
zip -r docs-built.zip docs
54+
55+
- name: Upload built doc artifact
56+
uses: actions/upload-artifact@v4
57+
with:
58+
name: built-docs-zip
59+
path: docs-built.zip
60+
retention-days: 10

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Update gh-pages-staging on commit
2+
3+
on:
4+
push:
5+
branches:
6+
- 4.x
7+
workflow_dispatch:
8+
9+
jobs:
10+
build-docs:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
15+
steps:
16+
# 1. Checkout doc branch
17+
- name: Checkout current branch
18+
uses: actions/checkout@v4
19+
with:
20+
path: java-driver
21+
22+
# 2. Java 8
23+
- name: Set up Java 8
24+
uses: actions/setup-java@v4
25+
with:
26+
distribution: temurin
27+
java-version: "8"
28+
cache: maven # <--- cache Maven deps (~/.m2/repository)
29+
30+
# 3. Python 3.10.19 + MkDocs + plugins
31+
- name: Set up Python 3.10.19
32+
uses: actions/setup-python@v5
33+
with:
34+
python-version: "3.10.19"
35+
36+
- name: Install MkDocs dependencies
37+
run: |
38+
python -m pip install --upgrade pip
39+
pip install \
40+
mkdocs \
41+
mkdocs-material \
42+
mkdocs-awesome-pages-plugin \
43+
mkdocs-macros-plugin
44+
45+
# 4. Build docs via build-doc.sh
46+
- name: Build documentation
47+
working-directory: java-driver
48+
run: |
49+
chmod +x ./build-doc.sh
50+
./build-doc.sh
51+
52+
53+
# 6. Checkout gh-pages-staging branch
54+
- name: Checkout gh-pages-staging
55+
uses: actions/checkout@v4
56+
with:
57+
ref: gh-pages-staging
58+
path: gh-pages-staging
59+
60+
- name: Copy and Build Doc
61+
working-directory: gh-pages-staging
62+
run: |
63+
cp -r ../java-driver/docs ./docs/latest
64+
mkdocs build
65+
cp -r ./out/. . # because the index.html has to be in the root folder
66+
67+
- name: Commit and push to gh-pages-staging
68+
working-directory: gh-pages-staging
69+
run: |
70+
git config --global user.email "[email protected]"
71+
git config --global user.name "GHA for Apache Cassandra Website"
72+
73+
git add .
74+
75+
if git diff --cached --quiet; then
76+
echo "No changes to push to gh-pages."
77+
exit 0
78+
fi
79+
80+
git commit -m "Update generated docs"
81+
git push origin gh-pages-staging

‎README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ are multiple modules, all prefixed with `java-driver-`.
4545
Note that the query builder is now published as a separate artifact, you'll need to add the
4646
dependency if you plan to use it.
4747

48-
Refer to each module's manual for more details ([core](manual/core/), [query
49-
builder](manual/query_builder/), [mapper](manual/mapper)).
48+
Refer to each module's manual for more details ([core](manual/core/README.md), [query
49+
builder](manual/query_builder/README.md), [mapper](manual/mapper/README.md)).
5050

5151
[org.apache.cassandra]: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.cassandra%22
5252

@@ -65,15 +65,15 @@ but DataStax does not officially support these systems.
6565
Java Driver 4 is **not binary compatible** with previous versions. However, most of the concepts
6666
remain unchanged, and the new API will look very familiar to 2.x and 3.x users.
6767

68-
See the [upgrade guide](upgrade_guide/) for details.
68+
See the [upgrade guide](upgrade_guide/README.md) for details.
6969

7070
## Error Handling
7171

7272
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;.
7373

7474
## Useful links
7575

76-
* [Manual](manual/)
76+
* [Manual](manual/README.md)
7777
* [API docs]
7878
* Bug tracking: [JIRA]
7979
* [Mailing list]
@@ -83,8 +83,8 @@ See the [Cassandra error handling done right blog](https://www.datastax.com/blog
8383
[API docs]: https://docs.datastax.com/en/drivers/java/4.17
8484
[JIRA]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CASSJAVA%20ORDER%20BY%20key%20DESC
8585
[Mailing list]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user
86-
[Changelog]: changelog/
87-
[FAQ]: faq/
86+
[Changelog]: changelog/README.md
87+
[FAQ]: faq/README.md
8888

8989
## License
9090

‎build-doc.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
set -e
2+
# Set up python environment
3+
#pyenv local 3.10.1
4+
#pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin mkdocs-macros-plugin
5+
6+
# In some bash/zsh environments, the locale is not set correctly, which causes mkdocs to fail.
7+
export LC_ALL=en_US.UTF-8
8+
export LANG=en_US.UTF-8
9+
10+
# Build Javadoc
11+
mvn clean install -DskipTests # or guava-shaded can not be found
12+
# mvn javadoc:javadoc -pl core,query-builder,mapper-runtime
13+
mvn javadoc:aggregate
14+
15+
# Build manual with API references
16+
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‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,8 +1022,8 @@ public enum DefaultDriverOption implements DriverOption {
10221022
* }
10231023
* </pre>
10241024
*
1025-
* Note: subnets must be represented as prefix blocks, see {@link
1026-
* inet.ipaddr.Address#isPrefixBlock()}.
1025+
* Note: subnets must be represented as prefix blocks, see <a
1026+
* href="https://javadoc.io/doc/com.github.seancfoley/ipaddress/latest/inet/ipaddr/Address.html#isPrefixBlock--">inet.ipaddr.Address.isPrefixBlock()</a>
10271027
*
10281028
* <p>Value type: {@link java.util.Map Map}&#60;{@link String},{@link String}&#62;
10291029
*/

‎core/src/main/java/com/datastax/oss/driver/api/core/data/CqlVector.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ public static <V> CqlVector<V> newInstance(List<V> list) {
8080
* Create a new CqlVector instance from the specified string representation.
8181
*
8282
* @param str a String representation of a CqlVector
83-
* @param subtypeCodec
83+
* @param subtypeCodec the codec to use to parse the individual elements
8484
* @return a new CqlVector built from the String representation
8585
*/
8686
public static <V> CqlVector<V> from(@NonNull String str, @NonNull TypeCodec<V> subtypeCodec) {

‎faq/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ At any rate, `CompletionStage` has a `toCompletableFuture()` method. In current
6565
### Where is `DowngradingConsistencyRetryPolicy` from driver 3?
6666

6767
**As of driver 4.10, this retry policy was made available again as a built-in alternative to the
68-
default retry policy**: see the [manual](../manual/core/retries) to understand how to use it.
68+
default retry policy**: see the [manual](../manual//core/retries/README.md) to understand how to use it.
6969
For versions between 4.0 and 4.9 inclusive, there is no built-in equivalent of driver 3
7070
`DowngradingConsistencyRetryPolicy`.
7171

@@ -100,7 +100,7 @@ This ability is considered a misfeature and has been removed from driver 4.0 onw
100100
However, due to popular demand, cross-datacenter failover has been brought back to driver 4 in
101101
version 4.10.0.
102102

103-
If you are using a driver version >= 4.10.0, read the [manual](../manual/core/loadbalancing/) to
103+
If you are using a driver version >= 4.10.0, read the [manual](../manual//core/load_balancing/README.md) to
104104
understand how to enable this feature; for driver versions < 4.10.0, this feature is simply not
105105
available.
106106

@@ -109,7 +109,7 @@ available.
109109
The driver now uses Java 8's improved date and time API. CQL type `timestamp` is mapped to
110110
`java.time.Instant`, and the corresponding getter and setter are `getInstant` and `setInstant`.
111111

112-
See [Temporal types](../manual/core/temporal_types/) for more details.
112+
See [Temporal types](../manual//core/temporal_types/README.md) for more details.
113113

114114
### Why do DDL queries have a higher latency than driver 3?
115115

@@ -119,6 +119,6 @@ noticeably higher latency than driver 3 (about 1 second).
119119
This is because those queries are now *debounced*: the driver adds a short wait in an attempt to
120120
group multiple schema changes into a single metadata refresh. If you want to mitigate this, you can
121121
either adjust the debouncing settings, or group your schema updates while temporarily disabling the
122-
metadata; see the [performance](../manual/core/performance/#debouncing) page.
122+
metadata; see the [performance](../manual//core/performance/README.md#debouncing) page.
123123

124124
This only applies to DDL queries; DML statements (`SELECT`, `INSERT`...) are not debounced.

‎manual/README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,16 @@ under the License.
2121

2222
Driver modules:
2323

24-
* [Core](core/): the main entry point, deals with connectivity and query execution.
25-
* [Query builder](query_builder/): a fluent API to create CQL queries programmatically.
26-
* [Mapper](mapper/): generates the boilerplate to execute queries and convert the results into
24+
* [Core](core/README.md): the main entry point, deals with connectivity and query execution.
25+
* [Query builder](query_builder/README.md): a fluent API to create CQL queries programmatically.
26+
* [Mapper](mapper/README.md): generates the boilerplate to execute queries and convert the results into
2727
application-level objects.
28-
* [Developer docs](developer/): explains the codebase and internal extension points for advanced
28+
* [Developer docs](developer/README.md): explains the codebase and internal extension points for advanced
2929
customization.
3030

3131
Common topics:
3232

33-
* [API conventions](api_conventions/)
34-
* [Case sensitivity](case_sensitivity/)
35-
* [OSGi](osgi/)
36-
* [Cloud](cloud/)
33+
* [API conventions](api_conventions/README.md)
34+
* [Case sensitivity](case_sensitivity/README.md)
35+
* [OSGi](osgi/README.md)
36+
* [Cloud](cloud/README.md)

‎manual/cloud/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -146,5 +146,5 @@ public class Main {
146146
[Create an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/creating-your-astra-database.html
147147
[Access an Astra database - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html#_sharing_your_secure_connect_bundle
148148
[Download the secure connect bundle - AWS/Azure/GCP]: https://docs.datastax.com/en/astra/docs/obtaining-database-credentials.html
149-
[minimal project structure]: ../core/integration/#minimal-project-structure
150-
[driver documentation]: ../core/configuration/
149+
[minimal project structure]: ../core/integration/README.md#minimal-project-structure
150+
[driver documentation]: ../core/configuration/README.md

0 commit comments

Comments
 (0)