Skip to content

(trunk) CASSANDRA-16763 Create Cassandra documentation content for new website #1128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
michaelsembwever wants to merge 4 commits into from
Closed

(trunk) CASSANDRA-16763 Create Cassandra documentation content for new website #1128

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
568d973
CASSANDRA-16763: Migrate documentation to AsciiDoc
polandll Jul 9, 2020
317a53a
CASSANDRA-16763: Update doc tooling and generated files
ossarga Sep 15, 2021
b3840e8
CASSANDRA-16763: Updated license check and gitignore
ossarga Dec 17, 2021
0d6f4e8
SQUASH ME - make `ant gen-doc` work again (in a preliminary way). upd…
michaelsembwever Dec 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
3 changes: 3 additions & 0 deletions .build/build-rat.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
<exclude name="**/cassandra.yaml"/>
<exclude name="**/cassandra-murmur.yaml"/>
<exclude name="**/cassandra-seeds.yaml"/>
<exclude NAME="**/doc/antora.yml"/>
<exclude name="**/test/conf/cassandra.yaml"/>
<exclude name="**/test/conf/cassandra_deprecated_parameters_names.yaml"/>
<exclude name="**/test/conf/cassandra_encryption.yaml"/>
Expand All @@ -69,6 +70,8 @@
<exclude name="**/tools/cqlstress-example.yaml"/>
<exclude name="**/tools/cqlstress-insanity-example.yaml"/>
<exclude name="**/tools/cqlstress-lwt-example.yaml"/>
<!-- Documentation files -->
<exclude NAME="**/doc/modules/**/*"/>
<!-- NOTICE files -->
<exclude NAME="**/NOTICE.md"/>
<!-- LICENSE files -->
Expand Down
5 changes: 3 additions & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,9 @@ Thumbs.db
.ant_targets

# Generated files from the documentation
doc/source/configuration/cassandra_config_file.rst
doc/source/tools/nodetool
doc/modules/cassandra/pages/configuration/cass_yaml_file.adoc
doc/modules/cassandra/pages/tools/nodetool/
doc/modules/cassandra/examples/TEXT/NODETOOL/

# Python virtual environment
venv/
Expand Down
22 changes: 0 additions & 22 deletions doc/Dockerfile
View file
Open in desktop

This file was deleted.

296 changes: 0 additions & 296 deletions doc/Makefile
View file
Open in desktop

This file was deleted.

19 changes: 9 additions & 10 deletions doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ 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/`
- 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.
Expand All @@ -36,20 +36,19 @@ Official documentation
----------------------

The source for the official documentation for Apache Cassandra can be found in
the `source` subdirectory. The documentation uses [sphinx](http://www.sphinx-doc.org/)
and is thus written in [reStructuredText](http://docutils.sourceforge.net/rst.html).
the `source` subdirectory. The documentation uses [antora](http://www.antora.org/)
and is thus written in [asciidoc](http://asciidoc.org).

To build the HTML documentation, you will need to first install antora and the
[Apache Cassandra theme](https://???). To add search, [lunr](https://lunrjs.com) must be installed.

To build the HTML documentation, you will need to first install sphinx and the
[sphinx ReadTheDocs theme](https://pypi.org/project/sphinx_rtd_theme/).
When using Python 3.6 on Windows, use `py -m pip install sphinx sphinx_rtd_theme`, on unix
use:
```
pip install sphinx sphinx_rtd_theme
npm i -g @antora/cli @antora/site-generator-default
npm install lunr
```

The documentation can then be built from this directory by calling `make html`
(or `make.bat html` on windows). Alternatively, the top-level `ant gen-doc`
target can be used. When using Python 3.6 on Windows, use `sphinx_build -b html source build`.
Alternatively, the top-level `ant gen-doc` target can be used.
Copy link
Member Author

@michaelsembwever michaelsembwever Dec 23, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ant gen-doc no longer works. (because doc/Makefile is removed)

There is now way to generate docs from the cassandra directory (everything is now done here).

Is there a minimum doc/Makefile we can put in place so that ant gen-doc runs in a basic form, for the sake of catching breakages…?

In fact… can we move some of that docker-entrypoint.sh back into doc/Makefile ?

Copy link
Member Author

@michaelsembwever michaelsembwever Dec 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see
polandll#16
and
apache/cassandra-website#86

Copy link
Contributor

@ossarga ossarga Dec 23, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. I guess we have a Makefile that does part of what the generate_cassandra_versioned_docs function in the docker-entrypoint.sh does. That is, build the jar files, then call the nodetool and cassandra configuration adoc generation scripts. This would be the most that gen-doc could do and should be enough to weed out any breakages. The README also needs to be updated. We would need to make this change on all three branches.

As a bonus, we could probably update the generate_cassandra_versioned_docs function to call ant gen-doc.

Copy link
Member Author

@michaelsembwever michaelsembwever Dec 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, covered in the PRs above.

But… i'm going to change the Makefile and ant targets for compatibility reasons.

Generating in-tree docs: ant gen-doc and make html are for a full antora build of the in-tree docs. This won't be implemented in these PRs, but will be reserved for when it is. (We had previously spoken about being able to create non-styled antora docs, even something that can be put into man pages.)

New targets for generating the dynamic adoc pages: ant gen-asciidoc and make gen-asciidoc.
The former will be called from the generate_cassandra_versioned_docs function.

Copy link
Member Author

@michaelsembwever michaelsembwever Dec 24, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PRs updated accordingly. (#16 needs to be applied to three branches.)

Copy link
Member Author

@michaelsembwever michaelsembwever Dec 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's another commit for trunk in polandll#18 (i botched the squash me commit you merged in already)

Copy link
Member Author

@michaelsembwever michaelsembwever Dec 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR for cassandra-4.0 polandll#17

PR for cassandra-3.11 polandll#19


To build the documentation with Docker Compose, run:

Expand Down
9 changes: 9 additions & 0 deletions doc/antora.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
name: Cassandra
version: 'trunk'
display_version: 'trunk'
asciidoc:
attributes:
cass_url: 'http://cassandra.apache.org/'
nav:
- modules/ROOT/nav.adoc
- modules/cassandra/nav.adoc
Loading