Introduce docs from CPP Driver and adjust #357

wprzytula · 2025-08-07T16:16:33Z

Based on: #359
Fixes: #351

Hello, Docs!

Base: CPP Driver

CPP Driver setup

ScyllaDB CPP Driver had documentation set up based on DataStax CPP Driver's READMEs. We had used eval-rst command to transform those READMEs to sphinx-readable resource tree, similarly to what Rust Driver does.
There also had been API docs set up, by configuring conf.py to transform Doxygen-generated files to sphinx.

Transfer

Steps done with the non-API docs:

Imported the whole docs tree (organized in the Topics directory).
Renamed README.md -> index.md, as index is not displayed in the URL, which is desired (so it's futures/ instead of futures/README.md).
Replaced underscores in file names with hyphens. This is for URL parsers to correctly break it into words.
Replaced feature/index.md singleton pattern with feature.md to reduce needless directory nesting.
Replaced links to datastax resources with our resources. TODO(@dgarcia360): configure URL substitution rules to support versioning correctly. I've left a related TODO in the code.

I took the API docs generation method as-is. I leave it for @dgarcia360 to refine it.

Further adjustments

Cleanup

Steps done:

Deleted DSE-related topics, as we don't support DSE.
Deps:
- Ditched zlib dependency, as it was only used for DSE support in CPP Driver, and never used in ScyllaDB CPP Driver.
- Similarly, ditched Kerberos dependency, as it was only used for DSE support, and also we don't support custom authenticators.
  - As a bonus, deleted embedded_ads from Integration Tests, as it's related to DSE support using Kerberos.
- Stated that libuv is a non-mandatory dependency, as it is not used by the core ScyllaDB CPP Driver, only by tests and examples.
Removed FAQ section, as it was empty anyway.
Removed mentions of ancient Cassandra versions, both from the docs and from the code.
Deleted description of setting up ccm in a VM.
Fixed timestamp-generation docs to correctly mention client-side timestamp generation as the default.

Restructuring

Improved structure, so that topics are better grouped and organized.
- Extracted Getting Started guide.
- Extracted Architecture Overview.
- Split Configuration into separate topics.
- Grouped related things into Observability topic.
- Extracted Authentication topic.
- Dissipated ScyllaDB Specific by moving Shard Awareness to Load Balancing topic.

Substantive changes

Described callbacks limitations regarding executing blocking code.
Adjusted load balancing and retries documentation to reflect the current state of the code,
as it differs in some ways compared to the original DataStax CPP Driver.

Attempted to set up `sphinx` (the last two commits)

Extended conf.py to mimic CPP Driver's. This is to be reviewed and improved by @dgarcia360.
I tried to replace links to DataStax documentation with our links, but it requires further assistance from @dgarcia360.

Bonus

Found a typo in the RPM-generation script, which made it contain ${name} string instead of the actual name of the package. Fixed it in the process.

Pre-review checklist

I have split my patch into logically separate commits.
All commit messages clearly explain what they change and why.
PR description sums up the changes and reasons why they should be introduced.
~~[ ] I have implemented Rust unit tests for the features/changes introduced.~~
~~[ ] I have enabled appropriate tests in Makefile in {SCYLLA,CASSANDRA}_(NO_VALGRIND_)TEST_FILTER.~~
I added appropriate Fixes: annotations to PR description.

Doxyfile.in

Lorak-mmk · 2025-08-13T19:23:13Z

docs/source/index.md

+* ScyllaDB CPP Driver lessons - [part 1](https://university.scylladb.com/courses/using-scylla-drivers/lessons/cpp-driver-part-1/)
+  and [part 2](https://university.scylladb.com/courses/using-scylla-drivers/lessons/cpp-driver-part-2-prepared-statements/) at Scylla University.


Those lessons will need to be updated as well, right?

Yes. But I'm not going to do this as part of this PR.

Actually, how do they need to be updated? They mostly refer to the driver's API and basic working, so no special adjustments are needed IMO.

I didn't look at the lessons, but don't they describe how to install the driver? This section will probably need to be updated (but of course not in this PR)

don't they describe how to install the driver

No. They say:

To learn how to install it, see here.

So we need to update the link, that's it.

docs/source/topics/configuration/load_balancing.md

docs/source/topics/configuration/speculative_execution.md

docs/source/topics/configuration/performance_tips.md

docs/source/topics/configuration/index.md

docs/source/topics/configuration/nonsupported.md

docs/source/topics/basics/binding-parameters.md

`${name}` is not a valid metavariable in the spec file - it was not substituted. Instead, it should be `%{name}`.

This is to align with the convention of using "contents" as the main table of contents file in documentation projects, as in the Rust Driver.

In its place, real documentation will be added later.

Let's name the Rust driver with its full name for clarity.

The `Doxyfile.in` file, which is used by the documentation generation workflow, has been added to the project straight from the cpp-driver. It's yet to be adjusted.

The `Doxyfile.in` file, which is used by the documentation generation workflow, has been adjusted for this project.

Ancient Cassandra versions are not supported by the driver, so it makes no sense to mention them in documentation and code.

docs/schema: fix typo client-side-timestamps: fix typo docs/schema_metadata: fix typo

We're not supporting DSE Cloud.

We don't support DSE.

When 7 years ago the default timestamp generator was changed from server-side to client-side, the documentation was improperly updated to reflect that change. This commit corrects the documentation.

...and warn about possible pitfalls of not setting a serial consistency before executing a Lightweight Transaction (LWT).

The implementation of CPP-Rust Driver has a limitation that callbacks must not block, otherwise the driver will panic. This commit documents this limitation in the documentation of futures, mentioning the notable exception of calling (otherwise blocking) future functions on futures that are guaranteed to be ready.

I believe the new name fits better.

Datatypes-related topics are now grouped under a single `data-types` directory.

The new name better reflects the semantics of this category.

Copilot

Pull Request Overview

This PR introduces comprehensive documentation from the CPP Driver codebase and performs several cleanup tasks. The documentation is adapted for ScyllaDB, with outdated DataStax-specific references updated to reflect the current driver's capabilities. The PR also removes Kerberos/DSE support artifacts that are not relevant to the ScyllaDB CPP Driver.

Imports comprehensive documentation structure covering driver usage, configuration, and architecture
Updates all references from "Scylla" to "ScyllaDB" for consistency
Removes deprecated DSE-specific features including Kerberos authentication and zlib dependencies

Reviewed Changes

Copilot reviewed 67 out of 70 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/src/integration/tests/*.cpp	Updates reference naming from "Scylla" to "ScyllaDB" in test comments
tests/src/integration/integration.hpp	Updates comments and documentation references to use "ScyllaDB"
tests/src/integration/embedded_ads.hpp/.cpp	Removes DSE-specific Kerberos authentication test infrastructure
tests/CMakeLists.txt	Removes embedded ADS JAR configuration for DSE support
src/driver_config.hpp	Removes Kerberos and zlib dependency definitions
src/CMakeLists.txt	Removes Kerberos and zlib build configuration
scylla-rust-wrapper/src/*.rs	Updates comments to use "ScyllaDB" instead of "Scylla"
include/cassandra.h	Removes Cassandra version-specific documentation annotations
examples/schema_meta/schema_meta.c	Removes Cassandra version-specific conditional code
driver_config.hpp.in	Removes Kerberos and zlib configuration templates
docs/source/topics/*/.md	Adds comprehensive documentation covering driver usage, security, observability, and data types

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

docs/source/topics/using/keyspaces.md

docs/source/topics/using/data-types/index.md

This commit removes the Windows build instructions from the documentation. The Windows build process is no longer verified and maintained, and therefore the instructions are removed to avoid confusion.

zlib is not a dependency of the CPP Rust driver, as the underlying Rust Driver has its own static dependencies.

As zlib is not used in the CPP-Rust Driver at all (it was used in CPP Driver for DataStax Cloud functionalities), this commit removes all references to zlib from the build system.

The driver does not support Kerberos authentication anymore, so the documentation has been updated to remove references to Kerberos and its installation instructions.

The embedded_ads code is related to Kerberos authentication to DSE clusters, which is no longer supported in the CPP-Rust Driver.

As Kerberos is not used in the CPP-Rust Driver at all (it was used in CPP Driver for custom authentication), this commit removes all references to Kerberos from the build system.

libuv is used by the CPP-Rust Driver only for tests and some of the examples, so let's state that clearly. Also, let's remove exact build instructions for libuv, as they are prone to change with new releases and it's better for the user to refer to the libuv documentation.

wprzytula · 2025-08-20T08:14:34Z

@dgarcia360 Your review is needed, mainly for the last two commits. Feel free to push your commits with sphinx setup fixes on top of mine - I will amend mine with them once I'm back from vacation.

dgarcia360 · 2025-08-26T07:38:56Z

docs/Makefile

+	@if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi
+	cp -RL source/* $(SOURCEDIR)
+	# cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'


Lines 28 and 29 look ok.

We can remove lines 30–32 and set SOURCEDIR to source.

In this project, it does not appear necessary to copy the documentation to a separate _sources folder for post-processing. That workflow is only required in projects where files need to be renamed at runtime, such as converting README.md to index.md.

dgarcia360 · 2025-08-26T07:46:09Z

docs/source/conf.py

+    # Workaround to replace DataStax links
+    replacements = [
+        {"http://datastax.github.io/cpp-driver/api/cassandra.h/": "https://cpp-rust-driver.docs.scylladb.com/" + smv_latest_version + "/api"},
+        {"http://datastax.github.io/cpp-driver": "https://cpp-rust-driver.docs.scylladb.com/" + smv_latest_version},
+        {"http://docs.datastax.com/en/developer/cpp-driver/latest": "https://cpp-rust-driver.docs.scylladb.com/" + smv_latest_version},
+    ]
+    sphinx.add_config_value('replacements', replacements, True)
+    sphinx.connect('source-read', replace_relative_links)


There is only one reference to http://docs.datastax.com in this repository.

Lines 189-196 are only relevant for repositories forked from Datastax that contain unmaintained documentation.

I recommend deleting these lines and updating the affected links in the documentation to point to the correct Datastax resources.

dgarcia360 · 2025-08-26T07:47:37Z

docs/source/topics/security/tls.md

+
+**NOTE:** In this example keystore and truststore are identical.
+
+The following [guide](http://www.datastax.com/documentation/cassandra/2.1/cassandra/security/secureSSLClientToNode_t.html) has more information related to configuring TLS on ScyllaDB/Cassandra.


Is this link correct?

dgarcia360

Apologies for the delay. I left some comments.

Additionally, we might want to add doxygen/xml/ to .gitignore.

wprzytula added this to the 1.0.0 milestone Aug 7, 2025

wprzytula self-assigned this Aug 7, 2025

wprzytula added the documentation Improvements or additions to documentation label Aug 7, 2025

wprzytula force-pushed the introduce-docs branch from 61a7435 to b266a03 Compare August 13, 2025 09:48

wprzytula requested review from Lorak-mmk and Copilot August 13, 2025 09:48

wprzytula marked this pull request as ready for review August 13, 2025 09:49

This comment was marked as outdated.

Sign in to view

wprzytula force-pushed the introduce-docs branch 2 times, most recently from 87570af to 10a19ad Compare August 13, 2025 10:42

Lorak-mmk requested changes Aug 13, 2025

View reviewed changes

wprzytula added 19 commits August 14, 2025 12:21

release/redhat: fix typo

e3fba03

`${name}` is not a valid metavariable in the spec file - it was not substituted. Instead, it should be `%{name}`.

docs: rename index.rst to contents.rst

c6839c5

This is to align with the convention of using "contents" as the main table of contents file in documentation projects, as in the Rust Driver.

docs: delete the sample page

944995d

In its place, real documentation will be added later.

conf.py: update site description

280a427

Let's name the Rust driver with its full name for clarity.

import Doxyfile.in from cpp-driver

cd6fd9e

The `Doxyfile.in` file, which is used by the documentation generation workflow, has been added to the project straight from the cpp-driver. It's yet to be adjusted.

adjust Doxyfile.in from cpp-driver

0de457e

The `Doxyfile.in` file, which is used by the documentation generation workflow, has been adjusted for this project.

docs: import topics from cpp-driver

3084f52

codewide: Scylla -> ScyllaDB

f1c05c2

codewide: remove mentions of ancient Cassandras

7a9370d

Ancient Cassandra versions are not supported by the driver, so it makes no sense to mention them in documentation and code.

docs/tracing: fix typos

1d752f0

docs/schema: fix typo client-side-timestamps: fix typo docs/schema_metadata: fix typo

docs: delete cloud topic

bd78961

We're not supporting DSE Cloud.

docs: remove DSE features documentation

079149f

We don't support DSE.

docs: mention only currect default consistency

ad31cc5

docs: adjust for default client-side timestamps

935e23e

When 7 years ago the default timestamp generator was changed from server-side to client-side, the documentation was improperly updated to reflect that change. This commit corrects the documentation.

docs: describe default serial consistency

51527b9

...and warn about possible pitfalls of not setting a serial consistency before executing a Lightweight Transaction (LWT).

docs: add main index.md

a557f1b

docs: add API index.md

11c9827

docs: rename Features -> Overview

344e512

I believe the new name fits better.

wprzytula added 5 commits August 14, 2025 13:01

docs: client-configuration -> client-identity

b85430b

docs/configuration: add table of contents

d6f2e2c

docs/basics: group datatypes-related topics

780584a

Datatypes-related topics are now grouped under a single `data-types` directory.

docs/basic: add table of contents

7e8dbac

docs: basics -> using the driver

4c80957

The new name better reflects the semantics of this category.

wprzytula force-pushed the introduce-docs branch from 10a19ad to d14d896 Compare August 14, 2025 11:44

wprzytula requested review from Lorak-mmk, Copilot and annastuchlik August 14, 2025 11:45

Copilot AI reviewed Aug 14, 2025

View reviewed changes

docs/source/topics/using/keyspaces.md Outdated Show resolved Hide resolved

docs/source/topics/using/keyspaces.md Outdated Show resolved Hide resolved

docs/source/topics/using/data-types/index.md Outdated Show resolved Hide resolved

wprzytula added 13 commits August 14, 2025 14:11

docs: fix typos found by Copilot

ae06e33

docs/building: remove Windows section

69e661a

This commit removes the Windows build instructions from the documentation. The Windows build process is no longer verified and maintained, and therefore the instructions are removed to avoid confusion.

docs: remove mentions of zlib dependency

8e60341

zlib is not a dependency of the CPP Rust driver, as the underlying Rust Driver has its own static dependencies.

build system: remove zlib-related code

dd4695f

As zlib is not used in the CPP-Rust Driver at all (it was used in CPP Driver for DataStax Cloud functionalities), this commit removes all references to zlib from the build system.

docs: remove mentions of Kerberos dependency

a579cda

The driver does not support Kerberos authentication anymore, so the documentation has been updated to remove references to Kerberos and its installation instructions.

IT: remove embedded_ads code

c13e482

The embedded_ads code is related to Kerberos authentication to DSE clusters, which is no longer supported in the CPP-Rust Driver.

build system: remove Kerberos-related code

3059a1b

As Kerberos is not used in the CPP-Rust Driver at all (it was used in CPP Driver for custom authentication), this commit removes all references to Kerberos from the build system.

docs: update building & installation instructions

7ac356e

docs: list contents on the front page

250e4f6

README: update front description

1c5f18c

WIP: setup sphinx docs

7b77e66

WIP: URLs: DataStax -> ScyllaDB docs

5aeb383

wprzytula force-pushed the introduce-docs branch from d14d896 to 5aeb383 Compare August 14, 2025 12:11

Lorak-mmk approved these changes Aug 14, 2025

View reviewed changes

dgarcia360 reviewed Aug 26, 2025

View reviewed changes

		* ScyllaDB CPP Driver lessons - [part 1](https://university.scylladb.com/courses/using-scylla-drivers/lessons/cpp-driver-part-1/)
		and [part 2](https://university.scylladb.com/courses/using-scylla-drivers/lessons/cpp-driver-part-2-prepared-statements/) at Scylla University.


		NOTE: In this example keystore and truststore are identical.

		The following [guide](http://www.datastax.com/documentation/cassandra/2.1/cassandra/security/secureSSLClientToNode_t.html) has more information related to configuring TLS on ScyllaDB/Cassandra.

Introduce docs from CPP Driver and adjust #357

Are you sure you want to change the base?

Introduce docs from CPP Driver and adjust #357

Uh oh!

Conversation

wprzytula commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hello, Docs!

Base: CPP Driver

CPP Driver setup

Transfer

Further adjustments

Cleanup

Restructuring

Substantive changes

Attempted to set up sphinx (the last two commits)

Bonus

Pre-review checklist

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Lorak-mmk Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

wprzytula Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

wprzytula Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

Lorak-mmk Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

wprzytula Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wprzytula commented Aug 20, 2025

Uh oh!

dgarcia360 Aug 26, 2025 • 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!

dgarcia360 Aug 26, 2025 • 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!

dgarcia360 Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

dgarcia360 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wprzytula commented Aug 7, 2025 •

edited

Loading

Attempted to set up `sphinx` (the last two commits)

dgarcia360 Aug 26, 2025 •

edited

Loading

dgarcia360 Aug 26, 2025 •

edited

Loading