From afa8623ab8739f70b83c576a9f8f574f43a4c898 Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Wed, 25 Jun 2014 11:59:43 +1000 Subject: [PATCH 1/6] initial work to make a mockup Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: 8a4b79ca5016ae8de0f530ae394064dc5142e5a6 Component: engine --- components/engine/docs/theme/mkdocs/base.html | 23 ++++++++++++++++--- .../engine/docs/theme/mkdocs/css/main.css | 9 +++++--- 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/components/engine/docs/theme/mkdocs/base.html b/components/engine/docs/theme/mkdocs/base.html index 8f2bd0603a..0768b4c8f9 100644 --- a/components/engine/docs/theme/mkdocs/base.html +++ b/components/engine/docs/theme/mkdocs/base.html @@ -48,11 +48,28 @@
{% if current_page.title != '**HIDDEN**' %}
-
+

{{ current_page.title }}

-
- Edit on GitHub +
+
+ Edit on GitHub +
+
+ +
{% endif %} diff --git a/components/engine/docs/theme/mkdocs/css/main.css b/components/engine/docs/theme/mkdocs/css/main.css index 6b6ec3f731..3375f797da 100644 --- a/components/engine/docs/theme/mkdocs/css/main.css +++ b/components/engine/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; From 9bc7000fc7a2f3ccc0d98eb7bb254e80e5e569cc Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Wed, 16 Jul 2014 14:48:12 +1000 Subject: [PATCH 2/6] The UX spec Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: c550ad59006c6a0c99b88581bb4378accea63043 Component: engine --- components/engine/docs/theme/mkdocs/base.html | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/components/engine/docs/theme/mkdocs/base.html b/components/engine/docs/theme/mkdocs/base.html index 0768b4c8f9..04095141ea 100644 --- a/components/engine/docs/theme/mkdocs/base.html +++ b/components/engine/docs/theme/mkdocs/base.html @@ -52,20 +52,19 @@

{{ current_page.title }}

-
- Edit on GitHub -
From b3754356a2475ac9935fea47ab436cb22d88f3aa Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Mon, 21 Jul 2014 15:51:14 +1000 Subject: [PATCH 3/6] dynamically load a /versions.html_fragment file so that all old versions get the complete dropdown list of versions to select Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: 5cd0f0824d04a73fb798207231b47157a51604d5 Component: engine --- components/engine/docs/Dockerfile | 3 +++ components/engine/docs/release.sh | 10 ++++---- components/engine/docs/theme/mkdocs/base.html | 24 ++++++++++++------- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/components/engine/docs/Dockerfile b/components/engine/docs/Dockerfile index 329646ed01..516a6d843a 100644 --- a/components/engine/docs/Dockerfile +++ b/components/engine/docs/Dockerfile @@ -27,10 +27,13 @@ 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 "
  • Version v$i
    • " ; done > /docs/sources/versions.html_fragment &&\ GIT_BRANCH=$(cat /docs/GIT_BRANCH) &&\ GITCOMMIT=$(cat /docs/GITCOMMIT) &&\ AWS_S3_BUCKET=$(cat /docs/AWS_S3_BUCKET) &&\ 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/\$AWS_S3_BUCKET/$AWS_S3_BUCKET/g" /docs/theme/mkdocs/base.html diff --git a/components/engine/docs/release.sh b/components/engine/docs/release.sh index f6dc2ec59f..de54eb3f5f 100755 --- a/components/engine/docs/release.sh +++ b/components/engine/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 @@ -104,9 +109,6 @@ setup_s3 build_current_documentation upload_current_documentation -# Remove the last version - 1.0.2-dev -> 1.0 -MAJOR_MINOR="v${VERSION%.*}" - #build again with /v1.0/ prefix sed -i "s/^site_url:.*/site_url: \/$MAJOR_MINOR\//" mkdocs.yml build_current_documentation diff --git a/components/engine/docs/theme/mkdocs/base.html b/components/engine/docs/theme/mkdocs/base.html index 04095141ea..6505e26fcd 100644 --- a/components/engine/docs/theme/mkdocs/base.html +++ b/components/engine/docs/theme/mkdocs/base.html @@ -4,7 +4,7 @@ -{% 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" %} @@ -52,17 +52,13 @@

    {{ current_page.title }}

    -
    -
      +
      +
      • - Latest (Version 1.3) + Latest (Version {{ major_minor }}) -
          -
        • Version 1.3
          • -
        • Version 1.2
          • -
        • Version 1.1
          • -
        • Version 1.0
          • + @@ -148,6 +144,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) { From eb7d72cb32123a51370b67048b009d0d0a859217 Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Tue, 22 Jul 2014 17:21:03 +1000 Subject: [PATCH 4/6] the build cache is too agressive, and I am regularly getting builds using an old version - forcing the issue Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: 3853a9c612e3d19dadea26153c9cebaec8cd67a4 Component: engine --- components/engine/docs/Dockerfile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/components/engine/docs/Dockerfile b/components/engine/docs/Dockerfile index 516a6d843a..e1f6c5b548 100644 --- a/components/engine/docs/Dockerfile +++ b/components/engine/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/ &&\ From 7bd6a5929be9959f4199a503bf6d7ce6d3e62487 Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Tue, 22 Jul 2014 18:04:48 +1000 Subject: [PATCH 5/6] Add more details so I have more of an over-view of what I need to automate Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: 3472c006c4246977eb4fd8c9d55ab416eb5c3d50 Component: engine --- components/engine/hack/RELEASE-CHECKLIST.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/components/engine/hack/RELEASE-CHECKLIST.md b/components/engine/hack/RELEASE-CHECKLIST.md index c8daee4874..2209baa745 100644 --- a/components/engine/hack/RELEASE-CHECKLIST.md +++ b/components/engine/hack/RELEASE-CHECKLIST.md @@ -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 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 From 5fa2981ff01e85b60287872f5c4fde25574440a3 Mon Sep 17 00:00:00 2001 From: SvenDowideit Date: Tue, 22 Jul 2014 19:05:18 +1000 Subject: [PATCH 6/6] avoid publishing to the root unless specified, so old version releases only goto their own dir Docker-DCO-1.1-Signed-off-by: SvenDowideit (github: SvenDowideit) Upstream-commit: 4d109f6158c7607ee4cd9907b17ddba5f4d29d04 Component: engine --- components/engine/Makefile | 2 +- components/engine/docs/Dockerfile | 2 ++ components/engine/docs/release.sh | 10 ++++++++-- components/engine/docs/theme/mkdocs/base.html | 3 ++- components/engine/hack/RELEASE-CHECKLIST.md | 4 ++-- 5 files changed, 15 insertions(+), 6 deletions(-) diff --git a/components/engine/Makefile b/components/engine/Makefile index 444ac3c6a6..71a3f32ec6 100644 --- a/components/engine/Makefile +++ b/components/engine/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 diff --git a/components/engine/docs/Dockerfile b/components/engine/docs/Dockerfile index e1f6c5b548..345de92bd0 100644 --- a/components/engine/docs/Dockerfile +++ b/components/engine/docs/Dockerfile @@ -35,10 +35,12 @@ RUN VERSION=$(cat /docs/VERSION) &&\ 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 diff --git a/components/engine/docs/release.sh b/components/engine/docs/release.sh index de54eb3f5f..ba309aaea9 100755 --- a/components/engine/docs/release.sh +++ b/components/engine/docs/release.sh @@ -106,10 +106,16 @@ upload_current_documentation() { } setup_s3 -build_current_documentation -upload_current_documentation + +# 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/" diff --git a/components/engine/docs/theme/mkdocs/base.html b/components/engine/docs/theme/mkdocs/base.html index 6505e26fcd..2b2b9bcbcf 100644 --- a/components/engine/docs/theme/mkdocs/base.html +++ b/components/engine/docs/theme/mkdocs/base.html @@ -4,10 +4,11 @@ - {% 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 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" %} + {% if meta.page_description %}{% endif %} {% if meta.page_keywords %}{% endif %} diff --git a/components/engine/hack/RELEASE-CHECKLIST.md b/components/engine/hack/RELEASE-CHECKLIST.md index 2209baa745..ccdcaee020 100644 --- a/components/engine/hack/RELEASE-CHECKLIST.md +++ b/components/engine/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 @@ -267,7 +267,7 @@ 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.com docs-release +make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes docs-release ``` The docs will appear on http://docs.docker.com/ (though there may be cached