Make archive easier (#5231)

* Fix archive butterbar margin-top * Add archive script and layout
2026-03-27 06:18:55 +07:00 · 2018-01-29 16:55:37 -08:00
parent 84b61d2ecf
commit 08e7715762
6 changed files with 247 additions and 14 deletions
--- a/_layouts/archive-redirect.html
+++ b/_layouts/archive-redirect.html
@@ -0,0 +1,14 @@
+---
+layout: docs
+---
+<html>
+<head><title>{{ page.prod_title }}</title></head>
+<body>
+<h1>{{ page.prod_title }}</h1>
+<p>You are viewing an archive branch of the
+  <a href="https://docs.docker.com/">Docker documentation</a>, but
+  {{ prod_title }} documentation is not published in the current archive.
+  <a href="https://docs.docker.com/{{ page.prod_url }}/" target="_blank">Go to https://docs.docker.com/{{ page.prod_url }}/</a>
+  in a new tab.</p>
+</body>
+</html>
--- a/_scripts/fetch-upstream-resources.sh
+++ b/_scripts/fetch-upstream-resources.sh
@@ -5,17 +5,56 @@
 # Relies on the following environment variables which are usually set by
 # the Dockerfile. Uncomment them here to override for debugging

-# Parse some variables from _config.yml and make them available to this script
-# This only finds top-level variables with _version in them that don't have any
-# leading space. This is brittle!
+# Helper functino to deal with sed differences between osx and Linux
+# See https://stackoverflow.com/a/38595160
+sedi () {
+    sed --version >/dev/null 2>&1 && sed -i -- "$@" || sed -i "" "$@"
+}

-SOURCE="$1"
+# Assume non-local mode until we check for -l
+LOCAL=0

+while getopts ":hl" opt; do
+  case ${opt} in
+    l ) LOCAL=1
+        echo "Running in local mode"
+        break
+      ;;
+    \? ) echo "Usage: $0 [-h] | -l"
+         echo "When running in local mode, operates on the current working directory."
+         echo "Otherwise, operates on md_source in the scope of the Dockerfile"
+         break
+      ;;
+  esac
+done
+
+# Do some sanity-checking to make sure we are running this from the right place
+if [ $LOCAL -eq 1 ]; then
+  SOURCE="."
+  if ! [ -f _config.yml ]; then
+    echo "Could not find _config.yml. We may not be in the right place. Bailing."
+    exit 1
+  fi
+else
+  SOURCE="md_source"
+  if ! [ -d md_source ]; then
+    echo "Could not find md_source directory. We may not be running in the right place. Bailing."
+    exit 1
+  fi
+fi
+
+# Reasonable default to find the Markdown files
 if [ -z "$SOURCE" ]; then
  echo "No source passed in, assuming md_source/..."
  SOURCE="md_source"
 fi

+echo "Operating on contents of $SOURCE"
+
+# Parse some variables from _config.yml and make them available to this script
+# This only finds top-level variables with _version in them that don't have any
+# leading space. This is brittle!
+
 while read i; do
  # Store the key as a variable name and the value as the variable value
  varname=$(echo "$i" | sed 's/"//g' | awk -F ':' {'print $1'} | tr -d '[:space:]')
@@ -25,8 +64,7 @@ while read i; do
 done < <(cat ${SOURCE}/_config.yml |grep '_version:' |grep '^[a-z].*')

 # Replace variable in toc.yml with value from above
-#echo "Replacing the string 'site.latest_stable_docker_engine_api_version' in _data/toc.yml with $latest_stable_docker_engine_api_version"
-sed -i "s/{{ site.latest_stable_docker_engine_api_version }}/$latest_stable_docker_engine_api_version/g" ${SOURCE}/_data/toc.yaml
+sedi "s/{{ site.latest_stable_docker_engine_api_version }}/$latest_stable_docker_engine_api_version/g" ${SOURCE}/_data/toc.yaml

 # Engine stable
 ENGINE_SVN_BRANCH="branches/17.12"
@@ -100,7 +138,7 @@ wget -O ${SOURCE}/engine/api/v1.27/swagger.yaml https://raw.githubusercontent.co
 # directory into a new one in the docs git and change the index.html
 wget -O ${SOURCE}/engine/api/v1.28/swagger.yaml https://raw.githubusercontent.com/docker/docker/v17.04.0-ce/api/swagger.yaml || (echo "Failed 1.28 swagger download or the 1.28 directory doesn't exist" && exit -1)
 wget -O ${SOURCE}/engine/api/v1.29/swagger.yaml https://raw.githubusercontent.com/docker/docker/17.05.x/api/swagger.yaml || (echo "Failed 1.29 swagger download or the 1.29 directory doesn't exist" && exit -1)
-# New location for swagger.yaml for 17.06
+# New location for swagger.yaml for 17.06+
 wget -O ${SOURCE}/engine/api/v1.30/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/17.06/components/engine/api/swagger.yaml || (echo "Failed 1.30 swagger download or the 1.30 directory doesn't exist" && exit -1)
 wget -O ${SOURCE}/engine/api/v1.31/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/17.07/components/engine/api/swagger.yaml || (echo "Failed 1.31 swagger download or the 1.31 directory doesn't exist" && exit -1)
 wget -O ${SOURCE}/engine/api/v1.32/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/17.09/components/engine/api/swagger.yaml || (echo "Failed 1.32 swagger download or the 1.32 directory doesn't exist" && exit -1)
@@ -114,7 +152,7 @@ wget -O ${SOURCE}/edge/engine/reference/commandline/dockerd.md https://raw.githu

 # Add an admonition to the edge dockerd file
 EDGE_DOCKERD_INCLUDE='{% include edge_only.md section=\"dockerd\" %}'
-sed -i "s/^#\ daemon/${EDGE_DOCKERD_INCLUDE}/1" ${SOURCE}/edge/engine/reference/commandline/dockerd.md
+sedi "s/^#\ daemon/${EDGE_DOCKERD_INCLUDE}/1" ${SOURCE}/edge/engine/reference/commandline/dockerd.md

 # Get a few one-off files that we use directly from upstream
 wget -O ${SOURCE}/engine/reference/builder.md https://raw.githubusercontent.com/docker/docker-ce/"$ENGINE_BRANCH"/components/cli/docs/reference/builder.md || (echo "Failed engine/reference/builder.md download" && exit -1)
--- a/_scripts/make-archive-branch.sh
+++ b/_scripts/make-archive-branch.sh
@@ -0,0 +1,144 @@
+#!/bin/bash
+
+while getopts ":hv:s:" opt; do
+  case ${opt} in
+    v ) version="$OPTARG"
+        break
+      ;;
+    s ) SHA="$OPTARG"
+        break
+      ;;
+    \? ) echo "Usage: $0 [-h] | -v <docker-version> -s <GIT-SHA-OF-ARCHIVE>"
+         echo ""
+         echo "<docker-version> is in the format \"17.09\" without any \"v\" prepended."
+         echo "<GIT-SHA-OF-ARCHIVE> is a Git SHA which is the last commit before work started that doesn't apply to this archive."
+         break
+      ;;
+  esac
+done
+
+# If we can't find a version, exit gracefully
+if [ -z "$version" ]; then
+  echo "-v is a required argument and was not detected."
+  exit 1
+else
+  # Do some very basic and naive checks on the format
+  # We expect it to start with a number
+  if ! [[ $version =~ ^[1-9].*[0-9]$ ]]; then
+    echo "Invalid version. Expected numbers and dots, but got $version"
+    exit 1
+  fi
+fi
+
+# If we don't have a SHA for the archive, exit
+if [ -z "$SHA" ]; then
+  echo "-s is a required argument and was not detected."
+  exit 1
+fi
+
+# Exit if we are not running from a clean master
+
+BRANCH=$(git branch | grep '*' | awk {'print $2'})
+
+if [ "$BRANCH" != "master" ]; then
+  echo "You are on branch $BRANCH but an archive can only be created from master. Exiting."
+  exit 1
+fi
+
+## Make sure our working branch is clean
+
+BRANCH_STATUS=$(git diff --cached --exit-code)
+BRANCH_STATUS_UNTRACKED=$(git ls-files --other --directory --exclude-standard)
+
+if ! [ -z $BRANCH_STATUS -a -z $BRANCH_STATUS_UNTRACKED ]; then
+  echo "Branch has uncommitted changes or untracked files. Exiting to protect you."
+  echo "Use a fresh clone for this, not your normal working clone."
+  echo "If you don't want to set up all your remotes again,"
+  echo "recursively copy (cp -r on a mac) your docker.github.io directory to"
+  echo "a new directory like archive-clone and run this script again from there."
+  exit 1
+fi
+
+# Check out the SHA
+
+echo "Making archive based on $SHA"
+git pull -q
+git checkout -q ${SHA}
+status=$?
+
+if [ $status !- 0 ]; then
+  echo "Failed to check out $SHA. Exiting."
+  exit 1
+fi
+
+
+# Create the archive branch
+
+git checkout -b v"$version" && echo "Created branch v$version and checked it out."
+
+# Replace the Dockerfile, set the version
+cat Dockerfile.archive |sed "s/vXX/v${version}/g" > Dockerfile
+
+# Run _scripts/fetch_upstream_resources.sh once in local mode
+bash _scripts/fetch-upstream-resources.sh -l
+
+# Add a redirect page for each section that doesn't apply to the archives, where
+# the reader should look in the live content instead
+# Currently, this is:
+# /samples/
+# /docker-id/
+# /docker-cloud/
+# /docker-hub/
+# /docker-store/
+# These rely on _layout/archive-redirect.html
+
+only_live_contents=("samples" "docker-id" "docker-cloud" "docker-hub" "docker-store")
+
+for dir in "${only_live_contents[@]}"; do
+  echo "Replacing contents of $dir with a redirect stub"
+  # Figure out the title, which should be title case with spaces instead of dashes
+  dir_title=$(echo $dir | sed 's/-/\ /g' | awk '{for(i=1;i<=NF;i++){ $i=toupper(substr($i,1,1)) substr($i,2) }}1')
+  echo "dir_title is ${dir_title}"
+  rm -Rf \"$dir\"
+  cat << EOF > "$dir/index.html"
+---
+layout: archive-redirect
+prod_title: "$dir_title"
+prod_url: "$dir"
+---
+EOF
+
+done
+
+echo "You are almost done. There are FOUR manual steps left to do."
+echo "1.  Edit _data/toc.yaml and remove all the entries under the following"
+echo "    locations except for their roots. For instance, remove all of"
+echo "    /samples/ entries except /samples/ itself."
+echo "    A valid example for samples would look like:"
+
+cat << EOF
+samples:
+- sectiontitle: Sample applications
+  section:
+  - path: /samples/
+    title: Samples home
+EOF
+
+echo "    Do this for the following sections:"
+for dir in "${only_live_contents[@]}"; do
+  echo "        \/$dir\/"
+done
+
+echo "2.  Do a local build and run to test your archive."
+echo "        docker build -t archivetest ."
+echo "        docker run --rm -it -p 4000:4000 archivetest"
+
+echo "3.  After carefully reviewing the output of `git status` to make sure no"
+echo "    files are being added by mistake, Run the following to add and commit"
+echo "    all your changes, including new files:"
+echo "        git commit -m \"Created archive branch v$version\" -A"
+
+echo "4.  Push your archive to the upstream remote:"
+echo "        git push upstream v$version"
+
+
--- a/css/temp.css
+++ b/css/temp.css
@@ -1 +1,28 @@
+/*
+*
+* this css will be integrated into master. for now testing.......
+*
+*/

+/* Archive butterbar */
+#archive-butterbar {
+  padding-top: 10px;
+  padding-bottom: 10px;
+  min-height: 34px;
+  border: 1px solid #254356;
+  background-color: #FFE1C0;
+  color: #254356;
+  width: 100%;
+  z-index: 9999;
+}
+
+#archive-butterbar.top {
+  position: relative;
+  margin-top: 0;
+}
+
+/* Archive butterbar when the top nav is fixed */
+#archive-butterbar.fixed {
+  position: fixed;
+  top: 55px;
+}
--- a/js/archive.js
+++ b/js/archive.js
@@ -7,7 +7,7 @@ if (window.navigator.onLine) {
  var suppressButterBar = false;
  /* This JSON file contains a current list of all docs versions of Docker */
  $.getJSON("/js/archives.json", function(result){
-    var outerDivStart = '<div style="padding-top: 10px; padding-bottom: 10px; min-height: 34px; border: 1px solid #254356; background-color: #FFE1C0; color: #254356"><div class="container"><div style="text-align: center"><span id="archive-list">This is <b><a href="https://docs.docker.com/docsarchive/" style="color: #254356; text-decoration: underline !important">archived documentation</a></b> for Docker&nbsp;' + dockerVersion + '. Go to the <a style="color: #254356; text-decoration: underline !important" href="https://docs.docker.com/">latest docs</a> or a different version:&nbsp;&nbsp;</span>' +
+    var outerDivStart = '<div id="archive-butterbar"><div class="container"><div style="text-align: center"><span id="archive-list">This is <b><a href="https://docs.docker.com/docsarchive/" style="color: #254356; text-decoration: underline !important">archived documentation</a></b> for Docker&nbsp;' + dockerVersion + '. Go to the <a style="color: #254356; text-decoration: underline !important" href="https://docs.docker.com/">latest docs</a> or a different version:&nbsp;&nbsp;</span>' +
                               '<span style="z-index: 1001" class="dropdown">';
    var listStart = '<ul class="dropdown-menu" role="menu" aria-labelledby="archive-menu">';
    var listEnd = '</ul>';
@@ -31,6 +31,7 @@ if (window.navigator.onLine) {
        }
      }
    });
+
    // only append the butterbar if we are NOT the current version
    // Also set the isArchive variable to true if it's an archive. It defaults
    // to true, set in _layouts/docs.html. We default to true because it looks
@@ -38,12 +39,20 @@ if (window.navigator.onLine) {
    if ( suppressButterBar == false ) {
      $( 'body' ).prepend(outerDivStart + buttonCode + listStart + listItems.join("") + listEnd + outerDivEnd);
      isArchive = true;
+      // If the butterbar exists, deal with positioning it
+      // Depends on some logic in _layout/docs.html
+      $(document).scroll(function() {
+        if ( $( 'nav' ).hasClass( 'affix' ) ) {
+          $('#archive-butterbar').addClass('fixed').removeClass('top');
+        } else {
+          $('#archive-butterbar').addClass('top').removeClass('fixed');
+        }
+      });
    } else {
      isArchive = false;
      /* This is only relevant to /enterprise/index.md */
      if (document.getElementById('ee-version-div')) {
        document.getElementById('ee-version-div').textContent += "The latest version of Docker EE is {{ site.docker_ee_version }}.";
      }
-    }
-  });
-}
+    }  });
+}
--- a/js/docs.js
+++ b/js/docs.js
@@ -427,6 +427,9 @@ $(function () {
  $('[data-toggle="tooltip"]').tooltip()
 })

+// Enable glossary link popovers
+$('.glossLink').popover();
+
 // sync tabs with the same data-group
 window.onload = function() {
  $('.nav-tabs > li > a').click(function(e) {
@@ -454,5 +457,3 @@ window.onload = function() {
    //console.log("Keeping non-applicable elements hidden.");
  }
 };
-
-$('.glossLink').popover();