From 9a18d09b7d8270781a465a7d1351fcdbfbaf52be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wojciech=20B=C4=85czkowski?= Date: Wed, 28 May 2025 15:34:07 +0200 Subject: [PATCH 1/3] Replace `{eval-rst}` with `eval_rst` in manuals Currently the previews built using `{eval-rst}` and myst_parser look to be more broken than switching back to `eval_rst` directive and adding the version to the list of branches using recommonmark. Specifically what seems to be pretty important and does not work with myst are relative links found in text like word 'integration' linking to ` http://localhost:5500/scylla-4.19.0.x/manual/core/index.html#integration/ ` This link should not treat `integration` as an anchor but as a subpage. This change makes the `make preview` and `make test` fail as it seems those targets try to use myst which does not understand `eval_rst` and only in `multiversion` those sections are understood by lexer correctly. --- manual/README.md | 2 +- manual/core/README.md | 2 +- manual/core/configuration/README.md | 2 +- manual/core/metadata/README.md | 2 +- manual/core/statements/README.md | 2 +- manual/developer/README.md | 2 +- manual/developer/common/README.md | 2 +- manual/mapper/README.md | 2 +- manual/mapper/config/README.md | 2 +- manual/mapper/daos/README.md | 2 +- manual/query_builder/README.md | 2 +- manual/query_builder/schema/README.md | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-) diff --git a/manual/README.md b/manual/README.md index 582e5264b11..8411eb586f0 100644 --- a/manual/README.md +++ b/manual/README.md @@ -34,7 +34,7 @@ Common topics: * [Case sensitivity](case_sensitivity/) * [OSGi](osgi/) -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/core/README.md b/manual/core/README.md index bce32f27b03..f7e26b4d165 100644 --- a/manual/core/README.md +++ b/manual/core/README.md @@ -351,7 +351,7 @@ for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) { [CASSANDRA-10145]: https://issues.apache.org/jira/browse/CASSANDRA-10145 -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/core/configuration/README.md b/manual/core/configuration/README.md index 0c54988cd78..c5c23d2ea8e 100644 --- a/manual/core/configuration/README.md +++ b/manual/core/configuration/README.md @@ -556,7 +556,7 @@ config.getDefaultProfile().getInt(MyCustomOption.AWESOMENESS_FACTOR); [HOCON]: https://github.com/typesafehub/config/blob/master/HOCON.md [API conventions]: ../../api_conventions -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/core/metadata/README.md b/manual/core/metadata/README.md index 409ec1b0ac2..0eb6a0904a5 100644 --- a/manual/core/metadata/README.md +++ b/manual/core/metadata/README.md @@ -79,7 +79,7 @@ refreshed. See the [Performance](../performance/#debouncing) page for more detai [Metadata]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Metadata.html [Node]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Node.html -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/core/statements/README.md b/manual/core/statements/README.md index 08946bafb3c..8a4c2256131 100644 --- a/manual/core/statements/README.md +++ b/manual/core/statements/README.md @@ -83,7 +83,7 @@ can create execution profiles to capture common combinations of those options). [execute]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#execute-com.datastax.oss.driver.api.core.cql.Statement- [executeAsync]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#executeAsync-com.datastax.oss.driver.api.core.cql.Statement- -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/developer/README.md b/manual/developer/README.md index 63c1ea9d52a..73e6cf243f2 100644 --- a/manual/developer/README.md +++ b/manual/developer/README.md @@ -37,7 +37,7 @@ from lowest to highest level: If you're reading this on GitHub, the `.nav` file in each directory contains a suggested order. -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/developer/common/README.md b/manual/developer/common/README.md index cda61f3f182..489a46fdc1a 100644 --- a/manual/developer/common/README.md +++ b/manual/developer/common/README.md @@ -27,7 +27,7 @@ This covers utilities or concept that are shared throughout the codebase: * the [event bus](event_bus/) is used to decouple some of the internal components through asynchronous messaging. -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/mapper/README.md b/manual/mapper/README.md index a29f8e023c8..f77daf6c08d 100644 --- a/manual/mapper/README.md +++ b/manual/mapper/README.md @@ -172,7 +172,7 @@ You can decide which logs to enable using the standard SLF4J mechanisms (categor addition, if you want no logs at all, it's possible to entirely remove them from the generated code with the Java compiler option `-Acom.datastax.oss.driver.mapper.logs.enabled=false`. -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/mapper/config/README.md b/manual/mapper/config/README.md index 0154b03deaf..b974e5cce07 100644 --- a/manual/mapper/config/README.md +++ b/manual/mapper/config/README.md @@ -133,7 +133,7 @@ You will find the generated files in `build/generated/sources/annotationProcesso * [Java 14 records](record/) * [Scala](scala/) -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/mapper/daos/README.md b/manual/mapper/daos/README.md index 673583afd15..705f1bc9126 100644 --- a/manual/mapper/daos/README.md +++ b/manual/mapper/daos/README.md @@ -173,7 +173,7 @@ To control how the hierarchy is scanned, annotate interfaces with [@HierarchySca [@HierarchyScanStrategy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/mapper/annotations/HierarchyScanStrategy.html [Entity Inheritance]: ../entities/#inheritance -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/query_builder/README.md b/manual/query_builder/README.md index f8897a25c8b..037fefc81b9 100644 --- a/manual/query_builder/README.md +++ b/manual/query_builder/README.md @@ -213,7 +213,7 @@ For a complete tour of the API, browse the child pages in this manual: [DseQueryBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseQueryBuilder.html [DseSchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseSchemaBuilder.html -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: diff --git a/manual/query_builder/schema/README.md b/manual/query_builder/schema/README.md index 9443ae42629..0fe8edb8a6c 100644 --- a/manual/query_builder/schema/README.md +++ b/manual/query_builder/schema/README.md @@ -65,7 +65,7 @@ element type: [SchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/querybuilder/SchemaBuilder.html -```{eval-rst} +```eval_rst .. toctree:: :hidden: :glob: From b98cf8f21c54504b8554ef019cc492d9b850e4b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wojciech=20B=C4=85czkowski?= Date: Wed, 28 May 2025 16:02:35 +0200 Subject: [PATCH 2/3] Fix broken links in reconnection manual Those links redirect to internal API which is not a part of the generated javadoc, leading to 404 on visit. Instead redirect to code on github. --- manual/core/reconnection/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/core/reconnection/README.md b/manual/core/reconnection/README.md index 3eb6dad9c05..440f9573367 100644 --- a/manual/core/reconnection/README.md +++ b/manual/core/reconnection/README.md @@ -103,7 +103,7 @@ Note that the session is not accessible until it is fully ready: the `CqlSession call — or the future returned by `buildAsync()` — will not complete until the connection was established. -[ConstantReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/internal/core/connection/ConstantReconnectionPolicy.html +[ConstantReconnectionPolicy]: https://github.com/scylladb/java-driver/blob/scylla-4.19.0.x/core/src/main/java/com/datastax/oss/driver/internal/core/connection/ConstantReconnectionPolicy.java [DriverContext]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/context/DriverContext.html -[ExponentialReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/internal/core/connection/ExponentialReconnectionPolicy.html +[ExponentialReconnectionPolicy]: https://github.com/scylladb/java-driver/blob/scylla-4.19.0.x/core/src/main/java/com/datastax/oss/driver/internal/core/connection/ExponentialReconnectionPolicy.java [ReconnectionPolicy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/connection/ReconnectionPolicy.html From 4d77320d013e2aba69a8651a0c23727b004e2208 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wojciech=20B=C4=85czkowski?= Date: Wed, 28 May 2025 16:47:00 +0200 Subject: [PATCH 3/3] Add query-builder and mapper-runtime javadocs When generating documentation website pages move also generated javadoc for query-builder and mapper-runtime modules. Some links in manuals attempt to link to the javadoc for those modules and end up being broken without those javadocs included. --- docs/_utils/javadoc.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh index 0c39996f68b..58086ec15d9 100755 --- a/docs/_utils/javadoc.sh +++ b/docs/_utils/javadoc.sh @@ -15,3 +15,5 @@ mvn javadoc:javadoc -T 1C [ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR mkdir -p "$OUTPUT_DIR" mv -f core/target/site/apidocs/* $OUTPUT_DIR +cp -an query-builder/target/site/apidocs/* $OUTPUT_DIR +cp -an mapper-runtime/target/site/apidocs/* $OUTPUT_DIR