[docs][site] Add a note about Kudu version to doc pages.
Kudu documentation is specific to a Kudu version and we release
updated docs for every release. However we don't make it explicit that
the documentation applies to a specific version of Kudu.
This change basically adds a note about the Kudu version to most
docs by including a common file named top.adoc. This include
file can be used in future for other cases where a snippet needs
to be added in multiple files.
The docs that were left out didn't seem to be version specific and
hence didn't include the version note.
This'll apply the note to docs created henceforth for new releases and
existing docs won't get the update. In order to update the existing
docs for prior releases we'll have to update them manually.
Screenshots:
https://drive.google.com/file/d/1Tbbmbkj8KkCbtktSPsShUOHrox9PP39j/view
https://drive.google.com/file/d/11gyYJgR3jhHqKX6mXpvW9GGfnhb9b4_7/view
Upcoming change updates the landing page of releases linking the
versioned docs.
Change-Id: Ie391f32dd27b3464569d12b5b553c4ab84a95130
Reviewed-on: http://gerrit.cloudera.org:8080/17438
Tested-by: Kudu Jenkins
Reviewed-by: Grant Henke <granthenke@apache.org>
diff --git a/docs/administration.adoc b/docs/administration.adoc
index c48238e..456665f 100644
--- a/docs/administration.adoc
+++ b/docs/administration.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
== Starting and Stopping Kudu Processes
NOTE: These instructions are relevant only when Kudu is installed using operating system packages
diff --git a/docs/background_tasks.adoc b/docs/background_tasks.adoc
index 48faae1..85ea3c7 100644
--- a/docs/background_tasks.adoc
+++ b/docs/background_tasks.adoc
@@ -27,6 +27,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
Kudu relies on running background tasks for many important automatic
maintenance activities. These tasks include flushing data from memory to disk,
compacting data to improve performance, freeing up disk space, and more.
diff --git a/docs/command_line_tools_reference.adoc b/docs/command_line_tools_reference.adoc
index 5456d6e..fd7e216 100644
--- a/docs/command_line_tools_reference.adoc
+++ b/docs/command_line_tools_reference.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
// 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.
diff --git a/docs/configuration.adoc b/docs/configuration.adoc
index 3667528..6ce2a5c 100644
--- a/docs/configuration.adoc
+++ b/docs/configuration.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
== Configure Kudu
=== Configuration Basics
diff --git a/docs/configuration_reference.adoc b/docs/configuration_reference.adoc
index eedc23a..5088dee 100644
--- a/docs/configuration_reference.adoc
+++ b/docs/configuration_reference.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
// The contents of this file are generated from the output of the `--helpxml`
// flag for each binary, during the build of the documentation. Do not edit
// this file or the included files manually.
diff --git a/docs/hive_metastore.adoc b/docs/hive_metastore.adoc
index 9ec8fe1..2e14f37 100644
--- a/docs/hive_metastore.adoc
+++ b/docs/hive_metastore.adoc
@@ -27,6 +27,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
[[hive_metastore]]
## Overview
diff --git a/docs/installation.adoc b/docs/installation.adoc
index 1486919..2b07617 100644
--- a/docs/installation.adoc
+++ b/docs/installation.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
The Apache Kudu project only publishes source code releases, to deploy Kudu on a
cluster follow the steps below to build Kudu from source.
diff --git a/docs/known_issues.adoc b/docs/known_issues.adoc
index 3cdd719..fc9c07d 100644
--- a/docs/known_issues.adoc
+++ b/docs/known_issues.adoc
@@ -27,6 +27,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
== Schema
=== Primary keys
diff --git a/docs/metrics_reference.adoc b/docs/metrics_reference.adoc
index 5de8b04..0ec67ae 100644
--- a/docs/metrics_reference.adoc
+++ b/docs/metrics_reference.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
// The contents of this file are generated from the output of the
// `--dump_metrics_xml` flag for each binary, during the build of
// the documentation. Do not edit this file or the included files
diff --git a/docs/schema_design.adoc b/docs/schema_design.adoc
index 0c1e0a6..fc7800b 100644
--- a/docs/schema_design.adoc
+++ b/docs/schema_design.adoc
@@ -26,6 +26,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
[[schema_design]]
== Overview
diff --git a/docs/security.adoc b/docs/security.adoc
index 4df8754..3f28deb 100644
--- a/docs/security.adoc
+++ b/docs/security.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
Kudu includes security features which allow Kudu clusters to be hardened against
access from unauthorized users. This guide describes the security features
provided by Kudu. <<configuration>> lists essential configuration options when
diff --git a/docs/support/scripts/make_docs.sh b/docs/support/scripts/make_docs.sh
index 24f0077..087c460 100755
--- a/docs/support/scripts/make_docs.sh
+++ b/docs/support/scripts/make_docs.sh
@@ -31,7 +31,8 @@
set -e
usage() {
- echo usage: "$0 --build_root <path> --output_subdir <relative path> [--site <path to gh-pages checkout>]"
+ echo usage: "$0 --build_root <path> --output_subdir <relative path> --version <version>\
+ [--site <path to gh-pages checkout>]"
}
if [[ "$OSTYPE" == "linux-gnu"* ]]; then
@@ -89,6 +90,15 @@
NO_JEKYLL=1
shift
;;
+ --version|-v)
+ VERSION=$2
+ if [ -z "$VERSION" ]; then
+ usage
+ exit 1
+ fi
+ shift
+ shift
+ ;;
*)
echo unknown argument: $arg
exit 1
@@ -239,7 +249,11 @@
TEMPLATE_FLAG=""
fi
-bundle exec asciidoctor -d book $TEMPLATE_FLAG \
+# The top include file is also needed in the generated doc directory to be included
+# by docs like metrics_reference.adoc that are generated above.
+cp $SOURCE_ROOT/docs/top.adoc $GEN_DOC_DIR/
+
+bundle exec asciidoctor -d book $TEMPLATE_FLAG -a KUDU_VERSION="$VERSION" \
$SOURCE_ROOT/docs/*.adoc ${GEN_DOC_DIR}/*.adoc -D "$OUTPUT_DIR"
mkdir -p "$OUTPUT_DIR/images"
diff --git a/docs/support/scripts/make_site.sh b/docs/support/scripts/make_site.sh
index 1a76e05..b01e642 100755
--- a/docs/support/scripts/make_site.sh
+++ b/docs/support/scripts/make_site.sh
@@ -109,7 +109,8 @@
DOC_SUBDIR="docs"
rm -Rf "$RELEASE_OUTPUT_DIR/$DOC_SUBDIR"
$SOURCE_ROOT/docs/support/scripts/make_docs.sh --build_root $BUILD_ROOT --site "$SITE_OUTPUT_DIR" \
- --output_subdir "$RELEASE_SUBDIR/$DOC_SUBDIR"
+ --output_subdir "$RELEASE_SUBDIR/$DOC_SUBDIR" \
+ --version "$VERSION"
if [ -f "$RELEASE_OUTPUT_DIR/docs/index.html" ]; then
echo "Successfully built docs."
else
diff --git a/docs/top.adoc b/docs/top.adoc
new file mode 100644
index 0000000..7e1476f
--- /dev/null
+++ b/docs/top.adoc
@@ -0,0 +1,35 @@
+// 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.
+
+// This document is specifically meant to be included in parts using tags.
+// This document doesn't need a title however docs build breaks in jekyll templates without
+// a title.
+= Apache Kudu
+
+:author: Kudu Team
+:imagesdir: ./images
+:icons: font
+:doctype: book
+:backend: html5
+:sectlinks:
+:experimental:
+
+// tag::version[]
+NOTE: This document applies to Apache Kudu version {KUDU_VERSION}. Please consult the
+link:http://kudu.apache.org/releases/[documentation of the appropriate release] that's applicable
+to the version of the Kudu cluster.
+// end::version[]
diff --git a/docs/transaction_semantics.adoc b/docs/transaction_semantics.adoc
index f1fb301..a9a7995 100644
--- a/docs/transaction_semantics.adoc
+++ b/docs/transaction_semantics.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
****
This is a brief introduction to Kudu's transaction and consistency semantics. For an
in-depth technical exposition of most of what is mentioned here, and why it is correct,
diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc
index 0c60487..5b74da0 100644
--- a/docs/troubleshooting.adoc
+++ b/docs/troubleshooting.adoc
@@ -28,6 +28,8 @@
:sectlinks:
:experimental:
+include::top.adoc[tags=version]
+
== Startup Errors
[[req_hole_punching]]
