Add pointer to latest API ref (docker#4897)

Author: Misty Stanley-Jones

Dockerfile

@@ -27,7 +27,8 @@ ENV ENGINE_BRANCH="17.06.x"
 ENV DISTRIBUTION_SVN_BRANCH="branches/release/2.6"
 ENV DISTRIBUTION_BRANCH="release/2.6"
 
-RUN sh md_source/_scripts/fetch-upstream-resources.sh \
+RUN apk --update add bash \
+  && bash ./md_source/_scripts/fetch-upstream-resources.sh \
 	&& jekyll build -s md_source -d target --config md_source/_config.yml \
 	&& rm -rf target/apidocs/layouts \
 	&& find target -type f -name '*.html' -print0 | xargs -0 sed -i 's#href="https://docs.docker.com/#href="/#g' \

_config.yml

@@ -13,10 +13,13 @@ lsi: false
 url: https://docs.docker.com
 keep_files: ["v1.4", "v1.5", "v1.6", "v1.7", "v1.8", "v1.9", "v1.10", "v1.11", "v1.12", "v1.13", "v17.03", "v17.06"]
 
-# Component versions -- address like site.docker-ce_stable_version
-docker-ce_stable_version: "17.09"
-docker-ce_edge_version: "17.09"
-docker-ee_version: "17.06"
+# Component versions -- address like site.docker_ce_stable_version
+# You can't have - characters in these for non-YAML reasons
+
+docker_ce_stable_version: "17.09"
+latest_stable_docker_engine_api_version: "1.32"
+docker_ce_edge_version: "17.09"
+docker_ee_version: "17.06"
 compose_version: "1.16.1"
 machine_version: "0.12.2"
 distribution_version: "2.6"

_data/toc.yaml

@@ -608,10 +608,12 @@ reference:
     title: Get started
   - path: /engine/api/sdks/
     title: SDKs
-  - path: /engine/api/v1.32/
-    title: v1.32 Reference
-  - sectiontitle: Previous API versions
+  - path: /engine/api/latest/
+    title: v{{ site.latest_stable_docker_engine_api_version }} reference
+  - sectiontitle: API reference by version
     section:
+    - path: /engine/api/v1.32/
+      title: v1.32 Reference
     - path: /engine/api/version-history/
       title: Version history overview
     - path: /engine/api/v1.31/

_includes/ee-linux-install-reuse.md

@@ -151,7 +151,7 @@ You can install Docker EE in different ways, depending on your needs:
     ```bash
     $ sudo yum list docker-ee  --showduplicates | sort -r
 
-    docker-ee.x86_64         {{ site.docker-ee_version }}.ee.2-1.el7.{{ linux-dist }}          docker-ee-stable-17.06
+    docker-ee.x86_64         {{ site.docker_ee_version }}.ee.2-1.el7.{{ linux-dist }}          docker-ee-stable-17.06
     ```
 
     The contents of the list depend upon which repositories you have enabled,
@@ -246,7 +246,7 @@ upgrade Docker EE.
 
 1.  Go to the Docker EE repository URL associated with your
     trial or subscription in your browser. Go to
-    `{{ linux-dist-url-slug }}/7/x86_64/stable-{{ site.docker-ee_version }}/Packages` and
+    `{{ linux-dist-url-slug }}/7/x86_64/stable-{{ site.docker_ee_version }}/Packages` and
     download the `.{{ package-format | downcase }}` file for the Docker version
     you want to install.
 

_layouts/docs.html

@@ -248,7 +248,7 @@ <h1>{{ page.title }}</h1>{% endif %} {% if page.advisory %}
 	// Default to assuming this is an archive and hiding some stuff
 	// See js/archive.js and js/docs.js for logic relating to this
 	var isArchive = true;
-	var dockerVersion = 'v{{ site.docker-ce_stable_version }}';
+	var dockerVersion = 'v{{ site.docker_ce_stable_version }}';
 	</script>
 	<script src="/js/archive.js"></script>
 	<script src="/js/stickyfill.min.js"></script>

_scripts/fetch-upstream-resources.sh

@@ -5,6 +5,21 @@
 # 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!
+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:]')
+  varvalue=$(echo "$i" | sed 's/"//g' | awk -F ':' {'print $2'} | tr -d '[:space:]')
+  echo "Setting \$${varname} to $varvalue"
+  declare "$varname=$varvalue"
+done < <(cat md_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" md_source/_data/toc.yaml
+
 # Engine stable
 ENGINE_SVN_BRANCH="branches/17.09"
 ENGINE_BRANCH="17.09"

develop/sdk/index.md

@@ -44,10 +44,16 @@ go get github.com/docker/docker/client
 
 [Read the full Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).
 
+## View the API reference
+
+You can
+[view the reference for the latest version of the API](/engine/api/latest/)
+or [choose a specific version](/engine/api/version-history/).
+
 ## Versioned API and SDK
 
-The version of the Docker API you should use depends upon the version of your
-Docker daemon and Docker client.
+The version of the Docker Engine API you should use depends upon the version of
+your Docker daemon and Docker client.
 
 A given version of the Docker Engine SDK supports a specific version of the
 Docker Engine API, as well as all earlier versions. If breaking changes occur,
@@ -124,8 +130,9 @@ You can specify the API version to use, in one of the following ways:
 Use the following guidelines to choose the SDK or API version to use in your
 code:
 
-- If you're starting a new project, use the latest version, but do specify the
-  version you are using. This helps prevent surprises.
+- If you're starting a new project, use the
+  [latest version](/engine/api/latest/), but do specify the version you are
+  using. This helps prevent surprises.
 - If you need a new feature, update your code use at least the oldest version
   that supports the feature, and prefer the latest version you are able to use.
 - Otherwise, continue to use the version that your code is already using.

engine/api/latest/index.html

@@ -0,0 +1,6 @@
+---
+---
+<html>
+<head><meta http-equiv="refresh" content="0;url=/engine/api/v{{ site.latest_stable_docker_engine_api_version }}/" /></head>
+<body><p>Redirecting to the latest version of the Docker Engine API reference.</body>
+</html>

engine/installation/linux/docker-ce/binaries.md

@@ -163,7 +163,7 @@ the `dockerd.exe` and `docker.exe` binaries are included.
 1.  Use the following PowerShell commands to install and start Docker:
 
     ```none
-    PS C:\> Invoke-WebRequest https://download.docker.com/win/static/stable/x86_64//docker-{{ site.docker-ce_stable_version }}.0-ce.zip -UseBasicParsing -OutFile docker.zip
+    PS C:\> Invoke-WebRequest https://download.docker.com/win/static/stable/x86_64//docker-{{ site.docker_ce_stable_version }}.0-ce.zip -UseBasicParsing -OutFile docker.zip
 
     PS C:\> Expand-Archive docker.zip -DestinationPath $Env:ProgramFiles
 

engine/installation/linux/docker-ce/centos.md

@@ -151,7 +151,7 @@ from the repository.
     ```bash
     $ yum list docker-ce --showduplicates | sort -r
 
-    docker-ce.x86_64            {{ site.docker-ce_stable_version }}.ce-1.el7.centos             docker-ce-stable
+    docker-ce.x86_64            {{ site.docker_ce_stable_version }}.ce-1.el7.centos             docker-ce-stable
     ```
 
     The contents of the list depend upon which repositories are enabled, and

engine/installation/linux/docker-ce/debian.md

@@ -219,7 +219,7 @@ from the repository.
     ```bash
     $ apt-cache madison docker-ce
 
-    docker-ce | {{ site.docker-ce_stable_version }}.0~ce-0~debian | https://download.docker.com/linux/debian jessie/stable amd64 Packages
+    docker-ce | {{ site.docker_ce_stable_version }}.0~ce-0~debian | https://download.docker.com/linux/debian jessie/stable amd64 Packages
     ```
 
     The contents of the list depend upon which repositories are enabled. Choose

engine/installation/linux/docker-ce/fedora.md

@@ -144,7 +144,7 @@ from the repository.
     ```bash
     $ dnf list docker-ce  --showduplicates | sort -r
 
-    docker-ce.x86_64  {{ site.docker-ce_stable_version }}.0.fc24                               docker-ce-stable  
+    docker-ce.x86_64  {{ site.docker_ce_stable_version }}.0.fc24                               docker-ce-stable  
     ```
 
     The contents of the list depend upon which repositories are enabled, and

engine/installation/linux/docker-ce/ubuntu.md

@@ -205,7 +205,7 @@ the repository.
     ```bash
     $ apt-cache madison docker-ce
 
-    docker-ce | {{ site.docker-ce_stable_version }}.0~ce-0~ubuntu | {{ download-url-base }} xenial/stable amd64 Packages
+    docker-ce | {{ site.docker_ce_stable_version }}.0~ce-0~ubuntu | {{ download-url-base }} xenial/stable amd64 Packages
     ```
 
     The contents of the list depend upon which repositories are enabled. Choose

engine/installation/linux/docker-ee/suse.md

@@ -118,7 +118,7 @@ from the repository.
 
     ```bash
     $ sudo zypper addrepo \
-        <DOCKER-EE-URL>/sles/12.3/x86_64/stable-{{ site.docker-ee_version }} \
+        <DOCKER-EE-URL>/sles/12.3/x86_64/stable-{{ site.docker_ee_version }} \
         docker-ee-stable
     ```
 
@@ -168,7 +168,7 @@ from the repository.
 
       S | Name          | Type    | Version                               | Arch   | Repository    
       --+---------------+---------+---------------------------------------+--------+---------------
-        | docker-ee     | package | {{ site.docker-ee_version }}-1                 | x86_64 | docker-ee-stable
+        | docker-ee     | package | {{ site.docker_ee_version }}-1                 | x86_64 | docker-ee-stable
     ```
 
     The contents of the list depend upon which repositories you have enabled.
@@ -243,7 +243,7 @@ need to download a new file each time you want to upgrade Docker EE.
 
 1.  Go to the Docker EE repository URL associated with your
     trial or subscription in your browser. Go to
-    `sles/12.3/x86_64/stable-{{ site.docker-ee_version }}` and download the `.rpm` file for
+    `sles/12.3/x86_64/stable-{{ site.docker_ee_version }}` and download the `.rpm` file for
     the Docker version you want to install.
 
 2.  Import Docker's official GPG key:

engine/installation/linux/docker-ee/ubuntu.md

@@ -143,7 +143,7 @@ from the repository.
     $ sudo add-apt-repository \
        "deb [arch=amd64] <DOCKER-EE-URL>/ubuntu \
        $(lsb_release -cs) \
-       stable-{{ site.docker-ee_version }}"
+       stable-{{ site.docker_ee_version }}"
     ```
 
     **s390x**:
@@ -152,7 +152,7 @@ from the repository.
     $ sudo add-apt-repository \
        "deb [arch=s390x] {{ download-url-base }} \
        $(lsb_release -cs) \
-       stable-{{ site.docker-ee_version }}"
+       stable-{{ site.docker_ee_version }}"
     ```
 
 #### Install Docker EE
@@ -185,7 +185,7 @@ from the repository.
     ```bash
     $ apt-cache madison docker-ee
 
-    docker-ee | {{ site.docker-ee_version }}.0~ee-0~ubuntu-xenial | <DOCKER-EE-URL>/ubuntu xenial/stable amd64 Packages
+    docker-ee | {{ site.docker_ee_version }}.0~ee-0~ubuntu-xenial | <DOCKER-EE-URL>/ubuntu xenial/stable amd64 Packages
     ```
 
     The contents of the list depend upon which repositories are enabled,
@@ -239,7 +239,7 @@ a new file each time you want to upgrade Docker EE.
 
 1.  Go to the Docker EE repository URL associated with your
     trial or subscription in your browser. Go to
-    `ubuntu/x86_64/stable-{{ site.docker-ee_version }}` and download the `.deb` file for the
+    `ubuntu/x86_64/stable-{{ site.docker_ee_version }}` and download the `.deb` file for the
     Docker EE version you want to install.
 
 2.  Install Docker EE, changing the path below to the path where you downloaded

test.md

@@ -248,14 +248,14 @@ example, [swarm](glossary.md?term=swarm)).
 ## Site-wide variables
 
 Look in the top-level `_config.yml` for site-wide variables, such as
-`site.docker-ce_stable_version`. To use them, use Liquid like:
+`site.docker_ce_stable_version`. To use them, use Liquid like:
 
 ```liquid
-{% raw %}{{ site.docker-ce_stable_version }}{% endraw %}
+{% raw %}{{ site.docker_ce_stable_version }}{% endraw %}
 ```
 
-The current value of `site.docker-ce_stable_version` is
-{{ site.docker-ce_stable_version }}.
+The current value of `site.docker_ce_stable_version` is
+{{ site.docker_ce_stable_version }}.
 
 ## Mixing Markdown and HTML