cassandra/doc/README.md

Apache Cassandra documentation directory

This directory contains the documentation maintained in-tree for Apache Cassandra. This directory contains the following documents:

• The source of the official Cassandra documentation, in the source/modules subdirectory. See below for more details on how to edit/build that documentation.
• The specification(s) for the supported versions of native transport protocol.

Official documentation

The source for the official documentation for Apache Cassandra can be found in the modules/cassandra/pages subdirectory. The documentation uses antora and is thus written in asciidoc.

The antora.yml file is auto-generated and should not be manually edited. It is generated from the version in build.xml using scripts/gen-antora-yml.py and automatically detects whether building from a release tag or branch HEAD to set the appropriate full or short version.

The antora.yml and some of the asciidoc files are dynamically generated using ant gen-asciidoc.

Building HTML Pages

To build the HTML documentation for this version only, you have two options:

Option 1: Using globally installed Antora (requires Node.js, Antora and Pandoc installed):

ant gen-doc

This uses the site-local.yml antora playbook to build only the current in-tree version.

Option 2: Using Docker:

.build/docker/build-docs.sh

This uses the same Docker image as cassandra-website, with all tooling pre-installed.

The HTML will be generated in build/html/.

For building documentation across multiple Cassandra versions, see the build instructions in the cassandra-website repo.

Building Man Pages

Building the html documentation also generates a manpages file.

View the man page:

man ../build/man/cassandra-docs.7.gz

Note: This creates a single comprehensive reference manual (section 7) containing all documentation.