Automate Nodetool Documentation

patch by Andrew Baker ; reviewed by Jon Haddad for CASSANDRA-12672

.gitignore

@@ -75,3 +75,4 @@ lib/jsr223/scala/*.jar
 
 # Generated files from the documentation
 doc/source/configuration/cassandra_config_file.rst
+doc/source/tools/nodetool

CHANGES.txt

@@ -1,4 +1,5 @@
 4.0
+ * Add (automate) Nodetool Documentation (CASSANDRA-12672)
  * Update bundled cqlsh python driver to 3.7.0 (CASSANDRA-12736)
  * Reject invalid replication settings when creating or altering a keyspace (CASSANDRA-12681)
 

doc/Makefile

@@ -19,6 +19,8 @@ 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
@@ -60,6 +62,7 @@ clean:
 .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."
@@ -68,6 +71,7 @@ html:
 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
@@ -76,6 +80,7 @@ website: clean
 .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."
@@ -83,6 +88,7 @@ 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."
@@ -90,6 +96,7 @@ 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."
@@ -97,6 +104,7 @@ pickle:
 .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."
@@ -104,6 +112,7 @@ json:
 .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" \
@@ -112,6 +121,7 @@ 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" \
@@ -123,6 +133,7 @@ qthelp:
 .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."
@@ -133,6 +144,7 @@ applehelp:
 .PHONY: devhelp
 devhelp:
 	$(MAKE_CASSANDRA_YAML)
+	$(GENERATE_NODETOOL_DOCS)
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -144,6 +156,7 @@ 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."
@@ -151,6 +164,7 @@ 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."
@@ -158,6 +172,7 @@ 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."
@@ -167,6 +182,7 @@ latex:
 .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
@@ -175,6 +191,7 @@ latexpdf:
 .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
@@ -189,6 +206,7 @@ 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."
@@ -196,6 +214,7 @@ 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."
@@ -205,6 +224,7 @@ texinfo:
 .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
@@ -213,6 +233,7 @@ info:
 .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."
@@ -220,6 +241,7 @@ gettext:
 .PHONY: changes
 changes:
 	$(MAKE_CASSANDRA_YAML)
+	$(GENERATE_NODETOOL_DOCS)
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
@@ -227,6 +249,7 @@ 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 " \
@@ -235,6 +258,7 @@ linkcheck:
 .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."
@@ -242,6 +266,7 @@ doctest:
 .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."
@@ -249,6 +274,7 @@ coverage:
 .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."
@@ -256,6 +282,7 @@ 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."
@@ -263,6 +290,7 @@ 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."

doc/gen-nodetool-docs.py

@@ -0,0 +1,69 @@
+# 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.
+
+"""
+A script to use nodetool to generate documentation for nodetool
+"""
+
+import os
+import re
+import subprocess
+from subprocess import PIPE, Popen
+
+nodetool = "../bin/nodetool"
+outdir = "source/tools/nodetool"
+helpfilename = outdir + "/nodetool.txt"
+command_re = re.compile("(    )([_a-z]+)")
+commandRSTContent = ".. _{0}\n\n{0}\n-------\n\nUsage\n---------\n\n.. include:: {0}.txt\n  :literal:\n\n"
+
+# create the documentation directory
+if not os.path.exists(outdir):
+    os.makedirs(outdir)
+
+# create the base help file to use for discovering the commands
+def createHelpfile():
+    with open(helpfilename, "w+") as file:
+        subprocess.call([nodetool, "help"], stdout=file)
+
+# for a given command, create the help file and an RST file to contain it
+def createRST(command):
+    if command:
+        cmdName = command.group(0).strip()
+        cmdFilename = outdir + "/" + cmdName + ".txt"
+        rstFilename = outdir + "/" + cmdName + ".rst"
+        with open(cmdFilename, "w+") as cmdFile:
+            proc = Popen([nodetool, "help", cmdName], stdin=PIPE, stdout=PIPE)
+            (out, err) = proc.communicate()
+            cmdFile.write(out)
+        with open(rstFilename, "w+") as rstFile:
+            rstFile.write(commandRSTContent.format(cmdName))
+
+# create base file
+createHelpfile()
+
+# create the main usage page
+with open(outdir + "/nodetool.rst", "w+") as output:
+    with open(helpfilename, "r+") as helpfile:
+        output.write(".. _nodetool\n\nNodetool\n-------\n\nUsage\n---------\n\n")
+        for commandLine in helpfile:
+            command = command_re.sub(r'\n\1:doc:`\2` - ',commandLine)
+            output.write(command)
+
+# create the command usage pages
+with open(helpfilename, "rw+") as helpfile:
+    for commandLine in helpfile:
+        command = command_re.match(commandLine)
+        createRST(command)

doc/source/tools/index.rst

@@ -23,4 +23,4 @@ This section describes the command line tools provided with Apache Cassandra.
    :maxdepth: 1
 
    cqlsh
-   nodetool
+   nodetool/nodetool

doc/source/tools/nodetool.rst

@@ -1,22 +0,0 @@
-.. 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.
-
-.. _nodetool:
-
-Nodetool
---------
-
-.. todo:: Try to autogenerate this from Nodetool’s help.