diff --git a/.build/build-rat.xml b/.build/build-rat.xml index 600946d18e3..a1a17cdadc4 100644 --- a/.build/build-rat.xml +++ b/.build/build-rat.xml @@ -53,6 +53,7 @@ + @@ -69,6 +70,8 @@ + + diff --git a/.gitignore b/.gitignore index a634687d8f7..7d5e24d9e2b 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/build.xml b/build.xml index 54fa1045df7..17deaed2646 100644 --- a/build.xml +++ b/build.xml @@ -423,13 +423,14 @@ - + - + - - - + + + + diff --git a/doc/Dockerfile b/doc/Dockerfile deleted file mode 100644 index ed60904ba71..00000000000 --- a/doc/Dockerfile +++ /dev/null @@ -1,22 +0,0 @@ -# Dockerfile for building the Cassandra documentation. -# If wanting to regenerate the documentation from scratch, -# run `ant realclean` from the root directory of this project. - -FROM python:2.7 - -WORKDIR /usr/src/code - -RUN pip install --no-cache-dir sphinx sphinx_rtd_theme - -RUN apt-get update && apt-get install -y software-properties-common - -RUN wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | apt-key add - \ - && add-apt-repository --yes https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ \ - && apt-get update \ - && apt-get install -y adoptopenjdk-11-hotspot ant - - -RUN apt-get clean - -CMD CASSANDRA_USE_JDK11=true ant realclean gen-doc \ - && echo "The locally built documentation can be found here:\n\n build/html/index.html\n\n" diff --git a/doc/Makefile b/doc/Makefile index 17ef395090e..43acc1ee7c5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,296 +1,26 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -YAML_DOC_INPUT=../conf/cassandra.yaml -YAML_DOC_OUTPUT=source/configuration/cassandra_config_file.rst - -MAKE_CASSANDRA_YAML = python convert_yaml_to_rst.py $(YAML_DOC_INPUT) $(YAML_DOC_OUTPUT) - -GENERATE_NODETOOL_DOCS = python gen-nodetool-docs.py - -WEB_SITE_PRESENCE_FILE='source/.build_for_website' - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " website to make HTML files for the Cassandra website" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " applehelp to make an Apple Help Book" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " epub3 to make an epub3" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to check syntax errors of document sources" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - rm -f $(YAML_DOC_OUTPUT) +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +GENERATE_NODETOOL_DOCS = ./scripts/gen-nodetool-docs.py +MAKE_CASSANDRA_YAML = ./scripts/convert_yaml_to_adoc.py ../conf/cassandra.yaml ./modules/cassandra/pages/configuration/cass_yaml_file.adoc .PHONY: html html: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: website -website: clean - @touch $(WEB_SITE_PRESENCE_FILE) - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @rm $(WEB_SITE_PRESENCE_FILE) - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: dirhtml -dirhtml: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -.PHONY: singlehtml -singlehtml: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -.PHONY: pickle -pickle: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -.PHONY: json -json: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -.PHONY: htmlhelp -htmlhelp: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -.PHONY: qthelp -qthelp: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ApacheCassandraDocumentation.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ApacheCassandraDocumentation.qhc" - -.PHONY: applehelp -applehelp: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp - @echo - @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." - @echo "N.B. You won't be able to view it unless you put it in" \ - "~/Library/Documentation/Help or install it in your application" \ - "bundle." - -.PHONY: devhelp -devhelp: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/ApacheCassandraDocumentation" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ApacheCassandraDocumentation" - @echo "# devhelp" - -.PHONY: epub -epub: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -.PHONY: epub3 -epub3: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 - @echo - @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." - -.PHONY: latex -latex: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -.PHONY: latexpdf -latexpdf: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: latexpdfja -latexpdfja: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -.PHONY: text -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -.PHONY: man -man: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -.PHONY: texinfo -texinfo: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -.PHONY: info -info: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -.PHONY: gettext -gettext: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -.PHONY: changes -changes: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -.PHONY: linkcheck -linkcheck: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: xml -xml: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -.PHONY: pseudoxml -pseudoxml: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -.PHONY: dummy -dummy: - $(MAKE_CASSANDRA_YAML) - $(GENERATE_NODETOOL_DOCS) - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy - @echo - @echo "Build finished. Dummy builder generates no files." + @# hack until a local basic antora build is put in + +.PHONY: gen-asciidoc +gen-asciidoc: + @mkdir -p modules/cassandra/pages/tools/nodetool + @mkdir -p modules/cassandra/examples/TEXT/NODETOOL + python3 $(GENERATE_NODETOOL_DOCS) + python3 $(MAKE_CASSANDRA_YAML) diff --git a/doc/README.md b/doc/README.md index 25ca702cf2c..608d236cb75 100644 --- a/doc/README.md +++ b/doc/README.md @@ -23,52 +23,39 @@ 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. -- Additional documentation on the SASI implementation (`SASI.md`). TODO: we - should probably move the first half of that documentation to the general - documentation, and the implementation explanation parts into the wiki. 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 `modules/cassandra/pages` 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 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: +To generate the asciidoc files for cassandra.yaml and the nodetool commands, run (from project root): +```bash +ant gen-asciidoc ``` -pip install sphinx sphinx_rtd_theme +or (from this directory): + +```bash +make gen-asciidoc ``` -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`. -To build the documentation with Docker Compose, run: +(The following has not yet been implemented, for now see the build instructions in the [cassandra-website](https://github.com/apache/cassandra-website) repo.) +To build the documentation, run (from project root): ```bash -cd ./doc - -# build the Docker image -docker-compose build build-docs - -# build the documentation -docker-compose run build-docs +ant gen-doc ``` - -To regenerate the documentation from scratch, run: +or (from this directory): ```bash -# return to the root directory of the Cassandra project -cd .. - -# remove all generated documentation files based on the source code -ant realclean +make html ``` + diff --git a/doc/antora.yml b/doc/antora.yml new file mode 100644 index 00000000000..f9fa1480d18 --- /dev/null +++ b/doc/antora.yml @@ -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 diff --git a/doc/cql3/CQL.textile b/doc/cql3/CQL.textile index c60800ed06e..fae2119ae76 100644 --- a/doc/cql3/CQL.textile +++ b/doc/cql3/CQL.textile @@ -416,7 +416,6 @@ bc(syntax).. | ADD ( ( , )* ) | DROP | DROP ( ( , )* ) - | DROP COMPACT STORAGE | WITH