KUDU-1708. Document Kudu command-line tools

- Adds helpxml flag support to the kudu binary - Adds doc script and xslt to convert xml to asciidoc Change-Id: I9f484f772cbaeb385687d83a2665ae4d7292aaf5 Reviewed-on: http://gerrit.cloudera.org:8080/6525 Reviewed-by: Adar Dembo <[email protected]> Tested-by: Adar Dembo <[email protected]>
sundbp · Apr 4, 2017 · 2407c2c · 2407c2c
1 parent 7206041
commit 2407c2c
Show file tree

Hide file tree

Showing 10 changed files with 496 additions and 24 deletions.
diff --git a/docs/command_line_tools_reference.adoc b/docs/command_line_tools_reference.adoc
@@ -0,0 +1,36 @@
+// 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.
+
+[[command_line_tools_reference]]
+= Apache Kudu Command Line Tools Reference
+
+:author: Kudu Team
+:imagesdir: ./images
+:icons: font
+:toc: left
+:toclevels: 2
+:doctype: book
+:backend: html5
+:sectlinks:
+:experimental:
+
+// The contents of this file are generated from the output of the `--helpxml`
+// flag for the kudu tool, during the build of the documentation.
+// Do not edit this file or the included files manually.
+
+// This gets replaced by the script that builds the docs
+@@TOOLS_REFERENCE@@
diff --git a/docs/support/jekyll-templates/document.html.erb b/docs/support/jekyll-templates/document.html.erb
@@ -97,6 +97,7 @@ end %>
         :transaction_semantics, "Kudu Transaction Semantics",
         :contributing, "Contributing to Kudu",
         :configuration_reference, "Kudu Configuration Reference",
+        :command_line_tools_reference, "Kudu Command Line Tools Reference",
         :known_issues, "Known Issues and Limitations",
         :export_control, "Export Control Notice"
       ]

diff --git a/docs/support/scripts/make_docs.sh b/docs/support/scripts/make_docs.sh
@@ -167,6 +167,30 @@ cp $SOURCE_ROOT/docs/configuration_reference* $GEN_DOC_DIR/
 sed -i "s#@@CONFIGURATION_REFERENCE@@#${INCLUSIONS_SUPPORTED}#" ${GEN_DOC_DIR}/configuration_reference.adoc
 sed -i "s#@@CONFIGURATION_REFERENCE@@#${INCLUSIONS_UNSUPPORTED}#" ${GEN_DOC_DIR}/configuration_reference_unsupported.adoc
 
+# Create tool references
+echo "Running kudu --helpxml"
+(
+  # Reset environment to avoid affecting the default flag values.
+  for var in $(env | awk -F= '{print $1}' | egrep -i 'KUDU|GLOG'); do
+    echo "unset $var"
+    eval "unset $var"
+  done
+
+  # Create the XML file.
+  # This command exits with a nonzero value.
+  $BUILD_ROOT/bin/kudu --helpxml > ${GEN_DOC_DIR}/kudu.xml || true
+)
+
+# Create the supported config reference
+xsltproc \
+-o $GEN_DOC_DIR/command_line_tools.adoc \
+  $SOURCE_ROOT/docs/support/xsl/tool_to_asciidoc.xsl \
+${GEN_DOC_DIR}/kudu.xml
+
+# Add the includes to the cli tools reference files, replacing the template lines
+cp $SOURCE_ROOT/docs/command_line_tools_reference.adoc $GEN_DOC_DIR/
+sed -i "s#@@TOOLS_REFERENCE@@#include::command_line_tools.adoc[leveloffset=+1]\n#" ${GEN_DOC_DIR}/command_line_tools_reference.adoc
+
 # If we're generating the web site, pass the template which causes us
 # to generate Jekyll templates instead of full HTML.
 if [ -n "$SITE" ]; then

diff --git a/docs/support/xsl/tool_to_asciidoc.xsl b/docs/support/xsl/tool_to_asciidoc.xsl
@@ -0,0 +1,142 @@
+<?xml version="1.0"?>
+<!--
+
+Licensed 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.
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:output method="text"/>
+
+<!-- Normalize space -->
+<xsl:template match="text()">
+    <xsl:if test="normalize-space(.)">
+      <xsl:value-of select="normalize-space(.)"/>
+    </xsl:if>
+</xsl:template>
+
+<xsl:template match="AllModes">
+<!-- Inject the license text into the header -->
+////
+//
+// 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.
+////
+
+:author: Kudu Team
+:imagesdir: ./images
+:icons: font
+:toc: left
+:toclevels: 1
+:doctype: book
+:backend: html5
+:sectlinks:
+:experimental:
+
+= Command Hierarchy
+<xsl:apply-templates select="mode" mode="toc"/>
+
+= Command Details
+<xsl:apply-templates select="mode" mode="content"/>
+
+</xsl:template>
+
+<!-- Table of contents template -->
+<xsl:template match="mode|action" mode="toc">
+<xsl:variable name="depth" select="count(ancestor::*)"/>
+<xsl:variable name="ref"><xsl:if test="../name"><xsl:value-of select="../name"/>-</xsl:if><xsl:value-of select="name"/></xsl:variable>
+<!-- Print bullets at mode/action depth -->
+<xsl:for-each select="(//node())[$depth >= position()]">*</xsl:for-each> &lt;&lt;<xsl:value-of select="$ref"/>,<xsl:value-of select="name"/>&gt;&gt;
+<xsl:apply-templates select="mode|action" mode="toc"/>
+</xsl:template>
+
+<!-- Content for mode template -->
+<xsl:template match="mode" mode="content">
+<xsl:variable name="depth" select="count(ancestor::*) + 1"/>
+<!-- Create unique anchor with the parent name and name -->
+<xsl:variable name="anchor"><xsl:if test="../name"><xsl:value-of select="../name"/>-</xsl:if><xsl:value-of select="name"/></xsl:variable>
+[[<xsl:value-of select="$anchor"/>]]
+<!-- Print header level at mode depth -->
+<xsl:for-each select="(//node())[$depth >= position()]">=</xsl:for-each> `<xsl:value-of select="name"/>`: <xsl:value-of select="description"/>
+{empty} +
+<xsl:apply-templates select="mode|action" mode="content"/>
+</xsl:template>
+
+<!-- Content for action template -->
+<xsl:template match="action" mode="content">
+<xsl:variable name="depth" select="count(ancestor::*) + 1"/>
+<!-- Create unique anchor with the parent name and name -->
+<xsl:variable name="anchor"><xsl:if test="../name"><xsl:value-of select="../name"/>-</xsl:if><xsl:value-of select="name"/></xsl:variable>
+[[<xsl:value-of select="$anchor"/>]]
+<!-- Print header level at action depth -->
+<xsl:for-each select="(//node())[$depth >= position()]">=</xsl:for-each> `<xsl:value-of select="name"/>`: <xsl:value-of select="description"/>{nbsp}
+<xsl:if test="extra_description != ''"><xsl:value-of select="extra_description"/> +</xsl:if>
+*Usage:* +
+`<xsl:value-of select="usage"/>`
+{empty} +
+*Arguments:*
+[frame="topbot",options="header"]
+|===
+| Name |  Description | Type | Default
+<xsl:for-each select="argument">
+<!-- escape pipe character in description for use in tables -->
+<xsl:variable name="escaped_description">
+  <xsl:call-template name="string-replace-all">
+    <xsl:with-param name="text" select="description" />
+    <xsl:with-param name="replace" select="'|'" />
+    <xsl:with-param name="by" select="'\|'" />
+  </xsl:call-template>
+</xsl:variable>
+| <xsl:value-of select="name"/><xsl:if test="contains(kind, 'variadic')">...</xsl:if><xsl:if test="contains(kind, 'optional')"> (optional)</xsl:if>
+| <xsl:value-of select="$escaped_description"/>
+| <xsl:value-of select="type"/>
+| <xsl:choose><xsl:when test="default_value != ''">`<xsl:value-of select="default_value"/>`</xsl:when><xsl:otherwise>none</xsl:otherwise></xsl:choose>
+</xsl:for-each>
+|===
+{empty} +
+</xsl:template>
+
+<!-- Template to support string replacement in XSLT 1.0) -->
+<xsl:template name="string-replace-all">
+<xsl:param name="text" />
+<xsl:param name="replace" />
+<xsl:param name="by" />
+<xsl:choose>
+  <xsl:when test="contains($text, $replace)">
+    <xsl:value-of select="substring-before($text,$replace)" />
+    <xsl:value-of select="$by" />
+    <xsl:call-template name="string-replace-all">
+      <xsl:with-param name="text" select="substring-after($text,$replace)" />
+      <xsl:with-param name="replace" select="$replace" />
+      <xsl:with-param name="by" select="$by" />
+    </xsl:call-template>
+  </xsl:when>
+  <xsl:otherwise>
+    <xsl:value-of select="$text" />
+  </xsl:otherwise>
+</xsl:choose>
+</xsl:template>
+</xsl:stylesheet>
diff --git a/src/kudu/tools/CMakeLists.txt b/src/kudu/tools/CMakeLists.txt
@@ -32,6 +32,7 @@ set(LINK_LIBS
 add_library(kudu_tools_util
   color.cc
   data_gen_util.cc
+  tool_action.cc
   tool_action_common.cc
 )
 target_link_libraries(kudu_tools_util
@@ -56,7 +57,6 @@ target_link_libraries(ksck
 )
 
 add_executable(kudu
-  tool_action.cc
   tool_action_cluster.cc
   tool_action_fs.cc
   tool_action_local_replica.cc
@@ -112,3 +112,4 @@ ADD_KUDU_TEST_DEPENDENCIES(kudu-tool-test
 ADD_KUDU_TEST(kudu-ts-cli-test)
 ADD_KUDU_TEST_DEPENDENCIES(kudu-ts-cli-test
   kudu)
+ADD_KUDU_TEST(tool_action-test)
diff --git a/src/kudu/tools/kudu-tool-test.cc b/src/kudu/tools/kudu-tool-test.cc
@@ -277,6 +277,41 @@ void ToolTest::StartMiniCluster(int num_masters,
   ASSERT_OK(mini_cluster_->Start());
 }
 
+TEST_F(ToolTest, TestHelpXML) {
+  string stdout;
+  string stderr;
+  Status s = RunTool("--helpxml", &stdout, &stderr, nullptr, nullptr);
+
+  ASSERT_TRUE(s.IsRuntimeError());
+  ASSERT_FALSE(stdout.empty());
+  ASSERT_TRUE(stderr.empty());
+
+  // All wrapped in AllModes node
+  ASSERT_STR_MATCHES(stdout, "<\\?xml version=\"1.0\"\\?><AllModes>.*</AllModes>");
+
+  // Verify all modes are output
+  const vector<string> modes = {
+      "cluster",
+      "fs",
+      "local_replica",
+      "master",
+      "pbc",
+      "remote_replica",
+      "table",
+      "tablet",
+      "test",
+      "tserver",
+      "wal",
+      "dump",
+      "cmeta",
+      "change_config"
+  };
+
+  for (const auto& mode : modes) {
+    ASSERT_STR_MATCHES(stdout, Substitute(".*<mode><name>$0</name>.*</mode>.*", mode));
+  }
+}
+
 TEST_F(ToolTest, TestTopLevelHelp) {
   const vector<string> kTopLevelRegexes = {
       "cluster.*Kudu cluster",