Merge pull request #7151 from SvenDowideit/add-version-selection-ux

Add version selection ux to the Documentation.

Makefile

@@ -34,7 +34,7 @@ docs-shell: docs-build
 	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
 
 docs-release: docs-build
-	$(DOCKER_RUN_DOCS) "$(DOCKER_DOCS_IMAGE)" ./release.sh
+	$(DOCKER_RUN_DOCS) -e BUILD_ROOT "$(DOCKER_DOCS_IMAGE)" ./release.sh
 
 test: build
 	$(DOCKER_RUN_DOCKER) hack/make.sh binary cross test-unit test-integration test-integration-cli

docs/Dockerfile

@@ -16,6 +16,9 @@ RUN	pip install mkdocs
 # this version works, the current versions fail in different ways
 RUN	pip install awscli==1.3.9
 
+# make sure the git clone is not an old cache - we've published old versions a few times now
+ENV	CACHE_BUST Jul2014
+
 # get my sitemap.xml branch of mkdocs and use that for now
 RUN	git clone https://github.com/SvenDowideit/mkdocs	&&\
 	cd mkdocs/						&&\
@@ -27,12 +30,17 @@ ADD	MAINTAINERS /docs/sources/humans.txt
 WORKDIR	/docs
 
 RUN	VERSION=$(cat /docs/VERSION)								&&\
+        MAJOR_MINOR="${VERSION%.*}"								&&\
+	for i in $(seq $MAJOR_MINOR -0.1 1.0) ; do echo "<li><a class='version' href='/v$i'>Version v$i</a></li>" ; done > /docs/sources/versions.html_fragment &&\
 	GIT_BRANCH=$(cat /docs/GIT_BRANCH)							&&\
 	GITCOMMIT=$(cat /docs/GITCOMMIT)							&&\
 	AWS_S3_BUCKET=$(cat /docs/AWS_S3_BUCKET)						&&\
+	BUILD_DATE=$(date)									&&\
 	sed -i "s/\$VERSION/$VERSION/g" /docs/theme/mkdocs/base.html				&&\
+	sed -i "s/\$MAJOR_MINOR/v$MAJOR_MINOR/g" /docs/theme/mkdocs/base.html			&&\
 	sed -i "s/\$GITCOMMIT/$GITCOMMIT/g" /docs/theme/mkdocs/base.html			&&\
 	sed -i "s/\$GIT_BRANCH/$GIT_BRANCH/g" /docs/theme/mkdocs/base.html			&&\
+	sed -i "s/\$BUILD_DATE/$BUILD_DATE/g" /docs/theme/mkdocs/base.html				&&\
 	sed -i "s/\$AWS_S3_BUCKET/$AWS_S3_BUCKET/g" /docs/theme/mkdocs/base.html
 
 # note, EXPOSE is only last because of https://github.com/dotcloud/docker/issues/3525

docs/release.sh

@@ -27,6 +27,10 @@ if [ "$$AWS_S3_BUCKET" == "docs.docker.com" ]; then
 	fi
 fi
 
+# Remove the last version - 1.0.2-dev -> 1.0
+MAJOR_MINOR="v${VERSION%.*}"
+export MAJOR_MINOR
+
 export BUCKET=$AWS_S3_BUCKET
 
 export AWS_CONFIG_FILE=$(pwd)/awsconfig
@@ -69,7 +73,8 @@ upload_current_documentation() {
 
 	# a really complicated way to send only the files we want
 	# if there are too many in any one set, aws s3 sync seems to fall over with 2 files to go
-	endings=( json html xml css js gif png JPG ttf svg woff)
+	#  versions.html_fragment
+	endings=( json html xml css js gif png JPG ttf svg woff html_fragment )
 	for i in ${endings[@]}; do
 		include=""
 		for j in ${endings[@]}; do
@@ -101,13 +106,16 @@ upload_current_documentation() {
 }
 
 setup_s3
-build_current_documentation
-upload_current_documentation
 
-# Remove the last version - 1.0.2-dev -> 1.0
-MAJOR_MINOR="v${VERSION%.*}"
+# Default to only building the version specific docs so we don't clober the latest by accident with old versions
+if [ "$BUILD_ROOT" == "yes" ]; then
+	echo "Building root documentation"
+	build_current_documentation
+	upload_current_documentation
+fi
 
 #build again with /v1.0/ prefix
 sed -i "s/^site_url:.*/site_url: \/$MAJOR_MINOR\//" mkdocs.yml
+echo "Building the /$MAJOR_MINOR/ documentation"
 build_current_documentation
 upload_current_documentation "/$MAJOR_MINOR/"

docs/theme/mkdocs/base.html

@@ -4,10 +4,11 @@
   <meta charset="utf-8">
   <meta http-equiv="X-UA-Compatible" content="IE=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
-{% set docker_version = "$VERSION" %}{% set docker_commit = "$GITCOMMIT" %}{% set docker_branch = "$GIT_BRANCH" %}{% set aws_bucket = "$AWS_S3_BUCKET" %}
+  {% set docker_version = "$VERSION" %}{% set major_minor = "$MAJOR_MINOR" %}{% set docker_commit = "$GITCOMMIT" %}{% set docker_branch = "$GIT_BRANCH" %}{% set aws_bucket = "$AWS_S3_BUCKET" %}{% set build_date = "$BUILD_DATE" %}
   <meta name="docker_version" content="{{ docker_version }}">
   <meta name="docker_git_branch" content="{{ docker_branch }}">
   <meta name="docker_git_commit" content="{{ docker_commit }}">
+  <meta name="docker_build_date" content="{{ build_date }}">
 
   {% if meta.page_description %}<meta name="description" content="{{ meta.page_description[0] }}">{% endif %}
   {% if meta.page_keywords %}<meta name="keywords" content="{{ meta.page_keywords[0] }}">{% endif %}
@@ -48,11 +49,23 @@
   <div id="content" class="container">
 {% if current_page.title != '**HIDDEN**' %}
     <div class="row" id="top-header">
-      <div class="span8">
+      <div class="span7">
         <h1 class="header2">{{ current_page.title }}</h1>
       </div>
-      <div class="span4 text-right edit-on-github">
-        <a class="home-link3" href="https://github.com/dotcloud/docker/blob/master/docs/sources/{{ current_page.input_path }}" class="tertiary-nav">Edit on GitHub</a>
+      <div class="span5">
+        <div id="versionnav" class="span3 pull-right">
+          <ul class="nav version pull-right">
+            <li class="dropdown">
+              <a id="logged-in-header-username" class="dropdown-toggle" data-toggle="dropdown" href="#">
+		      Latest (Version {{ major_minor }})
+              </a>
+              <ul id="documentation-version-list" class="dropdown-menu pull-right">
+		<li role="presentation" class="divider"></li>
+		<li> <a class="home-link3 tertiary-nav" href="https://github.com/dotcloud/docker/blob/master/docs/sources/{{ current_page.input_path }}" >Edit on GitHub</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
       </div>
     </div>
 {% endif %}
@@ -132,6 +145,16 @@ piCId = '1482';
   });
   $(document).ready(function() {
     $('#content').css("min-height", $(window).height() - 553 );
+    // load the complete versions list
+    $.get("/versions.html_fragment", function( data ) {
+    	$('#documentation-version-list').prepend(data);
+	//remove any "/v1.1/" bits from font.
+	path = document.location.pathname.replace(/^\/v\d\.\d/, "");
+	$('#documentation-version-list a.version').each(function(i, e) {
+		e.href = e.href+path;
+		$(e).removeClass()
+	});
+    });
   })
   var userName = getCookie('docker_sso_username');
   if (userName) {

docs/theme/mkdocs/css/main.css

@@ -847,7 +847,8 @@ div + .form-inline {
 .navbar #usernav .nav li {
   padding-top: 15px;
 }
-.navbar #usernav .nav li a {
+.navbar #usernav .nav li a,
+#versionnav .nav li a.dropdown-toggle {
   font-size: 14px;
   font-weight: 400;
   color: #394d54;
@@ -856,10 +857,12 @@ div + .form-inline {
   padding: 0 20px 0 0;
   background: url("../img/nav/caret-down-user-icon.svg") no-repeat 100% 50%;
 }
-.navbar #usernav .nav li a:hover {
+.navbar #usernav .nav li a:hover,
+#versionnav .nav li a.dropdown-toggle:hover {
   background-image: url("../img/nav/caret-down-user-icon-over.svg");
 }
-.navbar #usernav .nav li ul li {
+.navbar #usernav .nav li ul li,
+#versionnav .version {
   padding: 0;
   margin: 0;
   height: 28px;

hack/RELEASE-CHECKLIST.md

@@ -146,7 +146,7 @@ To make a shared test at http://beta-docs.docker.io:
 (You will need the `awsconfig` file added to the `docs/` dir)
 
 ```bash
-make AWS_S3_BUCKET=beta-docs.docker.io docs-release
+make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
 ```
 
 ### 5. Commit and create a pull request to the "release" branch
@@ -249,6 +249,16 @@ branch afterwards!
 
 ### 11. Update the docs branch
 
+If this is a MAJOR.MINOR.0 release, you need to make an branch for the previous release's
+documentation:
+
+```bash
+git checkout -b docs-$PREVIOUS_MAJOR_MINOR docs
+git fetch
+git reset --hard origin/docs
+git push -f origin docs-$PREVIOUS_MAJOR_MINOR
+```
+
 You will need the `awsconfig` file added to the `docs/` directory to contain the
 s3 credentials for the bucket you are deploying to.
 
@@ -257,13 +267,15 @@ git checkout -b docs release || git checkout docs
 git fetch
 git reset --hard origin/release
 git push -f origin docs
-make AWS_S3_BUCKET=docs.docker.io docs-release
+make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes docs-release
 ```
 
-The docs will appear on http://docs.docker.io/ (though there may be cached
-versions, so its worth checking http://docs.docker.io.s3-website-us-west-2.amazonaws.com/).
+The docs will appear on http://docs.docker.com/ (though there may be cached
+versions, so its worth checking http://docs.docker.com.s3-website-us-east-1.amazonaws.com/).
 For more information about documentation releases, see `docs/README.md`.
 
+Ask Sven, or JohnC to invalidate the cloudfront cache using the CND Planet chrome applet.
+
 ### 12. Create a new pull request to merge release back into master
 
 ```bash