Merge pull request #15906 from nikhiljindal/updateAPIReference

Adding a script to verify api reference docs are upto date

docs/api-reference/extensions/v1beta1/definitions.html

@@ -1838,7 +1838,14 @@ Both these may change in the future. Incoming requests are matched against the h
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">stdin</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Whether this container should allocate a buffer for stdin in the container runtime. Default is false.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">stdinOnce</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
@@ -4178,7 +4185,7 @@ Populated by the system when a graceful deletion is requested. Read-only. More i
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-10-16 18:20:09 UTC
+Last updated 2015-10-20 20:12:06 UTC
 </div>
 </div>
 </body>

docs/api-reference/extensions/v1beta1/operations.html

@@ -4975,7 +4975,7 @@ span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-10-16 18:20:09 UTC
+Last updated 2015-10-20 20:12:06 UTC
 </div>
 </div>
 </body>

docs/api-reference/v1/definitions.html

@@ -4684,7 +4684,14 @@ The resulting set of endpoints can be viewed as:<br>
 </tr>
 <tr>
 <td class="tableblock halign-left valign-top"><p class="tableblock">stdin</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Whether this container should allocate a buffer for stdin in the container runtime. Default is false.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false.</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">stdinOnce</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">boolean</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
@@ -6797,7 +6804,7 @@ The resulting set of endpoints can be viewed as:<br>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-10-16 18:20:03 UTC
+Last updated 2015-10-20 20:12:00 UTC
 </div>
 </div>
 </body>

hack/update-api-reference-docs.sh

@@ -14,14 +14,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Generates updated api-reference docs from the latest swagger spec.
+# Usage: ./update-api-reference-docs.sh <absolute output path>
+
 set -o errexit
 set -o nounset
 set -o pipefail
 
-KUBE_ROOT=$(dirname "${BASH_SOURCE}")/../..
-V1_PATH="$PWD/${KUBE_ROOT}/docs/api-reference/v1/"
-V1BETA1_PATH="$PWD/${KUBE_ROOT}/docs/api-reference/extensions/v1beta1"
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+DEFAULT_OUTPUT_PATH="$PWD/${KUBE_ROOT}/docs/api-reference"
+OUTPUT=${1:-${DEFAULT_OUTPUT_PATH}}
+
+echo "Generating api reference docs at ${OUTPUT}"
+
+V1_PATH="${OUTPUT}/v1/"
+V1BETA1_PATH="${OUTPUT}/extensions/v1beta1"
 SWAGGER_PATH="$PWD/${KUBE_ROOT}/api/swagger-spec/"
+
+echo "Reading swagger spec from: ${SWAGGER_PATH}"
+
 mkdir -p $V1_PATH
 mkdir -p $V1BETA1_PATH
 
@@ -32,3 +43,5 @@ docker run -v $V1_PATH:/output -v ${SWAGGER_PATH}:/swagger-source gcr.io/google_
 docker run -v $V1BETA1_PATH:/output -v ${SWAGGER_PATH}:/swagger-source gcr.io/google_containers/gen-swagger-docs:v3 \
     v1beta1 \
     https://raw.githubusercontent.com/kubernetes/kubernetes/master/pkg/apis/extensions/v1beta1/register.go
+
+# ex: ts=2 sw=2 et filetype=sh

hack/verify-api-reference-docs.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# Copyright 2015 The Kubernetes Authors All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Verifies that api reference docs are upto date.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+
+kube::golang::setup_env
+
+API_REFERENCE_DOCS_ROOT="${KUBE_ROOT}/docs/api-reference"
+TMP_OUTPUT_DIR="${KUBE_ROOT}/_tmp/api-reference"
+TMP_ROOT="${KUBE_ROOT}/_tmp"
+
+# Generate API reference docs in tmp.
+"./hack/update-api-reference-docs.sh" "${TMP_OUTPUT_DIR}"
+
+echo "diffing ${API_REFERENCE_DOCS_ROOT} against freshly generated docs"
+ret=0
+diff -Naupr -I 'Last update' --exclude=*.md "${API_REFERENCE_DOCS_ROOT}" "${TMP_OUTPUT_DIR}" || ret=$?
+rm -rf "${TMP_ROOT}"
+if [[ $ret -eq 0 ]]
+then
+  echo "${API_REFERENCE_DOCS_ROOT} up to date."
+else
+  echo "${API_REFERENCE_DOCS_ROOT} is out of date. Please run hack/update-api-reference-docs.sh"
+  exit 1
+fi
+
+# ex: ts=2 sw=2 et filetype=sh