This is an automated email from the ASF dual-hosted git repository.
bankim pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/kudu.git
The following commit(s) were added to refs/heads/master by this push:
new 163799c [docs][site] Add a note about Kudu version to doc pages.
163799c is described below
commit 163799c385a1e69d281d8c33de9fdccc64bf4b6d
Author: Bankim Bhavsar <[email protected]>
AuthorDate: Wed May 12 15:12:18 2021 -0700
[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 <[email protected]>
---
docs/administration.adoc | 2 ++
docs/background_tasks.adoc | 2 ++
docs/command_line_tools_reference.adoc | 2 ++
docs/configuration.adoc | 2 ++
docs/configuration_reference.adoc | 2 ++
docs/hive_metastore.adoc | 2 ++
docs/installation.adoc | 2 ++
docs/known_issues.adoc | 2 ++
docs/metrics_reference.adoc | 2 ++
docs/schema_design.adoc | 2 ++
docs/security.adoc | 2 ++
docs/support/scripts/make_docs.sh | 18 ++++++++++++++++--
docs/support/scripts/make_site.sh | 3 ++-
docs/{configuration_reference.adoc => top.adoc} | 21 +++++++++------------
docs/transaction_semantics.adoc | 2 ++
docs/troubleshooting.adoc | 2 ++
16 files changed, 53 insertions(+), 15 deletions(-)
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 @@ while [[ $# > 0 ]] ; do
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 @@ else
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 @@ mkdir -p "$RELEASE_OUTPUT_DIR"
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/configuration_reference.adoc b/docs/top.adoc
similarity index 67%
copy from docs/configuration_reference.adoc
copy to docs/top.adoc
index eedc23a..7e1476f 100644
--- a/docs/configuration_reference.adoc
+++ b/docs/top.adoc
@@ -15,24 +15,21 @@
// specific language governing permissions and limitations
// under the License.
-[[configuration_reference]]
-= Apache Kudu Configuration Reference
+// 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
-: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 each binary, 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
-@@CONFIGURATION_REFERENCE@@
-
-include::configuration_reference_unsupported.adoc[leveloffset=+1]
+// 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]]
