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.

Set up `sphinx` (the last few commits)

Extended conf.py to mimic CPP Driver's. This has been reviewed by @dgarcia360.
I replaced links to DataStax documentation with our links, which allowed removal of the link replacement trick.

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.

The new name better reflects the semantics of this category.

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.

sphinx is configured to build the docs. doxygen is used to generate API documentation. The code is taken from the C++ Driver repo.

Doxygen outputs XML files to docs/source/api, and Sphinx converts them to RST files in docs/api during the build. Both directories should be ignored by git.

wprzytula · 2025-09-08T08:54:03Z

Changes:

added a small commit: docs/tls: remove reference to DataStax guide
all other changes are in the last 3 commits:
- removed DataStax links replacements from conf.py.
- added paths to .gitignore.

Ready for re-review. @dgarcia360

docs/source/conf.py

dgarcia360

LGTM, one minor comment

All links in the docs are updated to point to ScyllaDB docs, not DataStax. With this, we can remove the replacements-based workaround in conf.py.

The docs should: - list both `master` and at least the most recent stable tag; - properly highlight which version is the latest stable one; - highlight `master` as unstable. This commit achieves that, bringing the configuration in line with the Rust Driver's.

wprzytula · 2025-09-11T11:19:48Z

Changes:

addressed the last comment from @dgarcia360
added a commit that configures tags and categorizes versions as stable, unstable, and also chooses the latest one.

wprzytula · 2025-09-12T12:49:27Z

@dgarcia360 Could you take a look at this CI fail? https://github.com/scylladb/cpp-rust-driver/actions/runs/17674022220/job/50231868500

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 15 commits September 8, 2025 10:41

docs/basic: add table of contents

e2fdcc4

docs: basics -> using the driver

28e380a

The new name better reflects the semantics of this category.

docs: fix typos found by Copilot

8ade1ad

docs/building: remove Windows section

b153d6f

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

7e41906

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

a0af65e

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

30a68d8

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

07c5cca

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

d14c200

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

2e72964

docs: list contents on the front page

d8b65dc

README: update front description

ce89a9a

docs: setup sphinx

80a0a1c

sphinx is configured to build the docs. doxygen is used to generate API documentation. The code is taken from the C++ Driver repo.

.gitignore: add docs build files

75eeb05

Doxygen outputs XML files to docs/source/api, and Sphinx converts them to RST files in docs/api during the build. Both directories should be ignored by git.

wprzytula force-pushed the introduce-docs branch from 5aeb383 to c5ac0bb Compare September 8, 2025 08:52

wprzytula requested a review from dgarcia360 September 8, 2025 08:54

dgarcia360 reviewed Sep 11, 2025

View reviewed changes

docs/source/conf.py Outdated Show resolved Hide resolved

dgarcia360 reviewed Sep 11, 2025

View reviewed changes

wprzytula added 2 commits September 11, 2025 13:14

docs: DataStax -> ScyllaDB URLs

f3bc753

All links in the docs are updated to point to ScyllaDB docs, not DataStax. With this, we can remove the replacements-based workaround in conf.py.

wprzytula force-pushed the introduce-docs branch from c5ac0bb to 1114a17 Compare September 11, 2025 11:18

wprzytula requested review from dgarcia360 and Lorak-mmk September 11, 2025 11:20

dgarcia360 approved these changes Sep 12, 2025

View reviewed changes

wprzytula merged commit 2d4f1bc into scylladb:master Sep 12, 2025
10 checks passed

wprzytula deleted the introduce-docs branch September 12, 2025 12:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Introduce docs from CPP Driver and adjust #357

Introduce docs from CPP Driver and adjust #357

Uh oh!

wprzytula commented Aug 7, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Lorak-mmk Aug 13, 2025

Uh oh!

wprzytula Aug 14, 2025

Uh oh!

wprzytula Aug 14, 2025

Uh oh!

Lorak-mmk Aug 14, 2025

Uh oh!

wprzytula Aug 14, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wprzytula commented Sep 8, 2025

Uh oh!

Uh oh!

dgarcia360 left a comment

Uh oh!

wprzytula commented Sep 11, 2025

Uh oh!

Uh oh!

wprzytula commented Sep 12, 2025

Uh oh!

Uh oh!

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

Introduce docs from CPP Driver and adjust #357

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

Set up sphinx (the last few 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!

wprzytula commented Sep 8, 2025

Uh oh!

Uh oh!

dgarcia360 left a comment

Choose a reason for hiding this comment

Uh oh!

wprzytula commented Sep 11, 2025

Uh oh!

Uh oh!

wprzytula commented Sep 12, 2025

Uh oh!

Uh oh!

wprzytula commented Aug 7, 2025 •

edited

Loading

Set up `sphinx` (the last few commits)