Rework jekyll-tree build to add redirects from site root.

As described in the commit message for 5596d3b, the new docs.bazel.build site will have one directory per released version and a master directory for the latest documentation at HEAD. This change reworks the jekyll-tree script to construct a final Jekyll tree containing the documentation at HEAD with documentation under /versions/master and redirect pages at the site root for each documentation page. TESTED=scripts/serve-docs.sh RELNOTES: None PiperOrigin-RevId: 159920553
author: dzc <dzc@google.com> 2017-06-23 08:26:15 +0200
committer: Marcel Hlopko <hlopko@google.com> 2017-06-26 18:31:01 +0200
commit: 1d8cd59173e9c1e2fd7fd03dd4b2a0ae8a35ef4b (patch)
tree: 9fa2e8667ffd10f26ff5137c5697b50a7905bc2b /site
parent: f8e5e0d3ac189b314e99450b806d1b52cfdd62ad (diff)
5 files changed, 84 insertions, 52 deletions
diff --git a/site/_includes/head.html b/site/_includes/head.html
index 3eda1bd0f9..b85760db23 100644
--- a/site/_includes/head.html
+++ b/site/_includes/head.html
@@ -17,11 +17,11 @@
       // Do a shortcut so that be.bazel.build redirect to the build encyclopedia
       var be_url = new RegExp("^https?://be(\.bazel.build)?/?");
       if (be_url.test(current_url)) {
-        window.location.replace(current_url.replace(be_url, "https://bazel.build/docs/be/overview.html"));
+        window.location.replace(current_url.replace(be_url, "https://docs.bazel.build/be/overview.html"));
       }
       var be_url = new RegExp("^https?://be(\.bazel.build)?/([a-zA-Z0-9_-]+)([/#](.*))?");
       if (be_url.test(current_url)) {
-        window.location.replace(current_url.replace(be_url, "https://bazel.build/docs/be/$2.html#$4"));
+        window.location.replace(current_url.replace(be_url, "https://docs.bazel.build/be/$2.html#$4"));
       }
       // And a short to code reviews
       var cr_url = new RegExp("^https?://cr(\.bazel.build)?/([0-9]+)")
@@ -40,8 +40,7 @@
     <!-- Webfont -->
     <link href="//fonts.googleapis.com/css?family=RobotoDraft:300,400,500|Source+Code+Pro:400,500,700" rel="stylesheet">
 
-    <link rel="icon" type="image/png" href="/images/favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="/images/favicon-16x16.png" sizes="16x16" />
+    <link rel="shortcut icon" type="image/png" href="/images/favicon.ico">
 
     <!-- Bootstrap -->
     <link href="/assets/css/bootstrap.min.css" rel="stylesheet">
diff --git a/site/_layouts/redirect.html b/site/_layouts/redirect.html
index d2fb13ac48..2418143677 100644
--- a/site/_layouts/redirect.html
+++ b/site/_layouts/redirect.html
@@ -1,7 +1,7 @@
 <html>
   <head>
     <script>
-      window.location.replace("/versions/{{ site.default_version }}/{{ page.redirect }}" + window.location.hash);
+      window.location.replace("{{ page.redirect }}" + window.location.hash);
     </script>
   </head>
-</html>
+</html>
+\ No newline at end of file
diff --git a/site/_layouts/regular-redirect.html b/site/_layouts/regular-redirect.html
deleted file mode 100644
index 2418143677..0000000000
--- a/site/_layouts/regular-redirect.html
+++ /dev/null
@@ -1,7 +0,0 @@
-<html>
-  <head>
-    <script>
-      window.location.replace("{{ page.redirect }}" + window.location.hash);
-    </script>
-  </head>
-</html>
-\ No newline at end of file
diff --git a/site/docs/index.html b/site/docs/index.html
new file mode 100644
index 0000000000..b32fa5c8bf
--- /dev/null
+++ b/site/docs/index.html
@@ -0,0 +1,4 @@
+---
+layout: redirect
+redirect: bazel-overview.html
+---
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh
index 99e93d507e..5655ed462f 100755
--- a/site/jekyll-tree.sh
+++ b/site/jekyll-tree.sh
@@ -13,6 +13,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# This script constructs the final Jekyll tree by combining the static Jekyll
+# site files with generated documentation, such as the Build Encyclopedia and
+# Skylark Library. It then constructs the site directory structure for
+# Bazel documentation at HEAD by moving all documentation into the
+# /versions/master directory and adding redirects from the root of the site.
+# This way, URLs of the form https://docs.bazel.build/foo.html will be
+# redirected to https://docs.bazel.build/versions/master/foo.html.
+
 set -eu
 
 readonly OUTPUT=${PWD}/$1
@@ -32,56 +40,44 @@ readonly TMP=$(mktemp -d "${TMPDIR:-/tmp}/tmp.XXXXXXXX")
 readonly OUT_DIR="$TMP/out"
 trap "rm -rf ${TMP}" EXIT
 
+# TODO: Create a variant of this script for cutting versions of documentation
+# for Bazel releases. For that case, consider extracting the Git branch or tag
+# name to be used as the versioned directory name.
+readonly VERSION="master"
+readonly VERSION_DIR="$OUT_DIR/versions/$VERSION"
+
+# Unpacks the base Jekyll tree, Build Encyclopedia, Skylark Library, and
+# command line reference.
 function setup {
   mkdir -p "$OUT_DIR"
   cd "$OUT_DIR"
   tar -xf "${JEKYLL_BASE}"
-}
 
-# Unpack the Build Encyclopedia into docs/be
-function unpack_build_encyclopedia {
-  local be_dir="$OUT_DIR/docs/be"
+  mkdir -p "$VERSION_DIR"
+  mv "$OUT_DIR"/docs/* "$VERSION_DIR"
+  rm -r "$OUT_DIR"/docs
+
+  # Unpack the Build Encyclopedia into versions/master/be
+  local be_dir="$VERSION_DIR/be"
   mkdir -p "$be_dir"
   unzip -qq "$BE_ZIP" -d "$be_dir"
   mv "$be_dir/be-nav.html" "$OUT_DIR/_includes"
 
-  # Create redirects to each page in the Build Encyclopedia.
-  mkdir -p "$OUT_DIR/docs/be"
-  for f in $(find "$OUT_DIR/docs/be" -name "*.html"); do
-    local filename=$(basename "$f")
-    cat > "$OUT_DIR/docs/be/${filename}" <<EOF
----
-layout: redirect
-redirect: docs/be/${filename}
----
-EOF
-  done
-}
-
-# Unpack the Skylark Library into docs/skylark/lib
-function unpack_skylark_library {
-  local sl_dir="$OUT_DIR/docs/skylark/lib"
+  # Unpack the Skylark Library into versions/master/skylark/lib
+  local sl_dir="$VERSION_DIR/skylark/lib"
   mkdir -p "$sl_dir"
   unzip -qq "$SL_ZIP" -d "$sl_dir"
   mv "$sl_dir/skylark-nav.html" "$OUT_DIR/_includes"
 
-  # Create redirects to each page in the Skylark Library
-  mkdir -p "$OUT_DIR/docs/skylark/lib"
-  for f in $(find "$OUT_DIR/docs/skylark/lib" -name "*.html"); do
-    local filename=$(basename "$f")
-    cat > "$OUT_DIR/docs/skylark/lib/${filename}" <<EOF
----
-layout: redirect
-redirect: docs/skylark/lib/${filename}
----
-EOF
-  done
+  # Copy the command line reference.
+  cp "$CLR_HTML" "$VERSION_DIR"
 }
 
+# Helper function for copying a Skylark rule doc.
 function copy_skylark_rule_doc {
   local rule_family=$1
   local rule_family_name=$2
-  local be_dir="$OUT_DIR/docs/be"
+  local be_dir="$VERSION_DIR/be"
 
   ( cat <<EOF
 ---
@@ -92,6 +88,7 @@ EOF
     cat "$TMP/skylark/$rule_family/README.md"; ) > "$be_dir/${rule_family}.md"
 }
 
+# Copies the READMEs for Skylark rules bundled with Bazel.
 function unpack_skylark_rule_docs {
   local tmp_dir=$TMP/skylark
   mkdir -p $tmp_dir
@@ -101,6 +98,7 @@ function unpack_skylark_rule_docs {
   copy_skylark_rule_doc pkg "Packaging"
 }
 
+# Processes a documentation page, such as replacing Blaze with Bazel.
 function process_doc {
   local f=$1
   local tempf=$(mktemp -t bazel-doc-XXXXXX)
@@ -110,18 +108,58 @@ function process_doc {
   cat "$tempf" > "$f"
 }
 
+# Performs fixup on each doc, such as replacing instances of 'blaze' with
+# 'bazel'.
 function process_docs {
-  for f in $(find "$OUT_DIR/docs" -name "*.html"); do
+  for f in $(find "$VERSION_DIR" -name "*.html"); do
     process_doc $f
   done
-  for f in $(find "$OUT_DIR/docs" -name "*.md"); do
+  for f in $(find "$VERSION_DIR" -name "*.md"); do
     process_doc $f
   done
-  for f in $(find "$OUT_DIR/designs" -name "*.md"); do
-    process_doc $f
+}
+
+# Generates a redirect for a documentation page under /versions/master.
+function gen_redirect {
+  local output_dir=$OUT_DIR/$(dirname $f)
+  if [[ ! -d "$output_dir" ]]; then
+    mkdir -p "$output_dir"
+  fi
+
+  local src_basename=$(basename $f)
+  local md_basename="${src_basename%.*}.md"
+  local html_file="${f%.*}.html"
+  local redirect_file="$output_dir/$md_basename"
+  if [[ -e "$redirect_file" ]]; then
+    echo "Cannot create redirect file $redirect_file. File exists."
+    exit 1
+  fi
+  cat > "$redirect_file" <<EOF
+---
+layout: redirect
+redirect: /versions/$VERSION/$html_file
+---
+EOF
+}
+
+# During setup, all documentation under docs are moved to the /versions/master
+# directory as the documentation from HEAD.
+#
+# This function henerates a redirect from the root of the site for the given
+# doc page under /versions/master so that https://docs.bazel.build/foo.html
+# will be redirected to https://docs.bazel.build/versions/master/foo.html
+function gen_redirects {
+  pushd "$VERSION_DIR" > /dev/null
+  for f in $(find . -name "*.html" -type f); do
+    gen_redirect $f
+  done
+  for f in $(find . -name "*.md" -type f); do
+    gen_redirect $f
   done
+  popd > /dev/null
 }
 
+# Creates a tar archive containing the final Jekyll tree.
 function package_output {
   cd "$OUT_DIR"
   tar -hcf $OUTPUT $(find . -type f | sort)
@@ -129,11 +167,9 @@ function package_output {
 
 function main {
   setup
-  unpack_build_encyclopedia
-  unpack_skylark_library
   unpack_skylark_rule_docs
-  cp ${CLR_HTML} ${OUT_DIR}/docs
   process_docs
+  gen_redirects
   package_output
 }
 main
author	dzc <dzc@google.com>	2017-06-23 08:26:15 +0200
committer	Marcel Hlopko <hlopko@google.com>	2017-06-26 18:31:01 +0200
commit	1d8cd59173e9c1e2fd7fd03dd4b2a0ae8a35ef4b (patch)
tree	9fa2e8667ffd10f26ff5137c5697b50a7905bc2b /site
parent	f8e5e0d3ac189b314e99450b806d1b52cfdd62ad (diff)