You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by mc...@apache.org on 2016/10/07 05:52:24 UTC
cassandra git commit: Automate Nodetool Documentation
Repository: cassandra
Updated Branches:
refs/heads/trunk 324bd7187 -> b9191871c
Automate Nodetool Documentation
patch by Andrew Baker ; reviewed by Jon Haddad for CASSANDRA-12672
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/b9191871
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/b9191871
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/b9191871
Branch: refs/heads/trunk
Commit: b9191871c32d3ab06030548c9fa63e0cab43c6c7
Parents: 324bd71
Author: mck <mi...@semb.wever.org>
Authored: Fri Oct 7 16:43:25 2016 +1100
Committer: mck <mi...@semb.wever.org>
Committed: Fri Oct 7 16:52:18 2016 +1100
----------------------------------------------------------------------
.gitignore | 1 +
CHANGES.txt | 1 +
doc/Makefile | 28 ++++++++++++++++
doc/gen-nodetool-docs.py | 69 ++++++++++++++++++++++++++++++++++++++
doc/source/tools/index.rst | 2 +-
doc/source/tools/nodetool.rst | 22 ------------
6 files changed, 100 insertions(+), 23 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/.gitignore
----------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
index f5b1ce1..76c4bd1 100644
--- a/.gitignore
+++ b/.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
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/CHANGES.txt
----------------------------------------------------------------------
diff --git a/CHANGES.txt b/CHANGES.txt
index b5d5bf4..2783b9f 100644
--- a/CHANGES.txt
+++ b/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)
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/doc/Makefile
----------------------------------------------------------------------
diff --git a/doc/Makefile b/doc/Makefile
index 81d7707..88ceaaf 100644
--- a/doc/Makefile
+++ b/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."
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/doc/gen-nodetool-docs.py
----------------------------------------------------------------------
diff --git a/doc/gen-nodetool-docs.py b/doc/gen-nodetool-docs.py
new file mode 100644
index 0000000..ae01534
--- /dev/null
+++ b/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)
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/doc/source/tools/index.rst
----------------------------------------------------------------------
diff --git a/doc/source/tools/index.rst b/doc/source/tools/index.rst
index 5a5e4d5..bdb98fd 100644
--- a/doc/source/tools/index.rst
+++ b/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
http://git-wip-us.apache.org/repos/asf/cassandra/blob/b9191871/doc/source/tools/nodetool.rst
----------------------------------------------------------------------
diff --git a/doc/source/tools/nodetool.rst b/doc/source/tools/nodetool.rst
deleted file mode 100644
index e373031..0000000
--- a/doc/source/tools/nodetool.rst
+++ /dev/null
@@ -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\u2019s help.