natas_hw
/
cassandra
mirror of https://github.com/apache/cassandra
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
cassandra/doc
History
Lorina Poland 05b0eaecad
Migrate documentation to AsciiDoc 
This commit sets up a new documentation structure and format:

* The directory struture changes from a Sphinx project to an Antora module layout.
* The formatting of the content changes from reStructuredText to AsciiDoc.

The documentation must now be built and published with Antora. Initially only from the cassandra-website repository.

This change was done to make maintaining versioned website documentation easier. As Antora is designed to generate versioned documentation.

The old directory structure was:

<ROOT>
  - doc/
    - cql3/
      - CQL.css
      - CQL.textile
    - source/
      - _static/
      - _templates/
      - _theme/
      - _util/
      - <other directory sections>/
      - conf.py
      - index.rst
      - <other *.rst pages>
    - make.bat
    - Makefile
    - README.md
    - SASI.md
    - <*.spec files>
    - <generation scripts>

The new directory structure organises the documentation into modules:

<ROOT>
  - doc/
    - cql3
    - modules/
      - cassandra/
        - assets/
        - examples/
        - pages/
        - partials/
        - nav.adoc
      - ROOT/
        - pages/
        - nav.adoc
    - scripts/
    - antora.yaml
    - README.md
    - SASI.md

 patch by Lorina Poland, Anthony Grasso; reviewed by Anthony Grasso, Mick Semb Wever for CASSANDRA-16763

Co-authored-by: Anthony Grasso <anthony@thelastpickle.com>
 		2022-01-05 22:03:02 +01:00
..
cql3 Merge branch 'cassandra-3.0' into cassandra-3.11 2021-04-19 17:34:05 +02:00
modules Migrate documentation to AsciiDoc 2022-01-05 22:03:02 +01:00
scripts Migrate documentation to AsciiDoc 2022-01-05 22:03:02 +01:00
Makefile Migrate documentation to AsciiDoc 2022-01-05 22:03:02 +01:00
README.md Migrate documentation to AsciiDoc 2022-01-05 22:03:02 +01:00
antora.yml Migrate documentation to AsciiDoc 2022-01-05 22:03:02 +01:00
native_protocol_v3.spec Merge branch 'cassandra-3.0' into cassandra-3.11 2021-04-19 17:34:05 +02:00
native_protocol_v4.spec Merge branch 'cassandra-3.0' into cassandra-3.11 2021-04-19 17:34:05 +02:00
native_protocol_v5.spec Merge branch 'cassandra-3.0' into cassandra-3.11 2021-04-19 17:34:05 +02:00

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.

To generate the asciidoc files for cassandra.yaml and the nodetool commands, run (from project root):

ant gen-asciidoc

or (from this directory):

make gen-asciidoc

(The following has not yet been implemented, for now see the build instructions in the cassandra-website repo.) To build the documentation, run (from project root):

ant gen-doc

or (from this directory):

make html