Linking to API object definitions from docs

nikhiljindal · Jul 20, 2015 · 021138b · 021138b
1 parent 7dab0af
commit 021138b
Show file tree

Hide file tree

Showing 8 changed files with 40 additions and 1 deletion.
diff --git a/build/mark-new-version.sh b/build/mark-new-version.sh
@@ -92,6 +92,7 @@ fi
 echo "+++ Versioning documentation and examples"
 
 # Update the docs to match this version.
+HTML_PREVIEW_PREFIX="https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes"
 md_dirs=(docs examples)
 md_files=()
 for dir in "${md_dirs[@]}"; do
@@ -102,6 +103,10 @@ for doc in "${mdfiles[@]}"; do
       -e '/<!-- BEGIN STRIP_FOR_RELEASE -->/,/<!-- END STRIP_FOR_RELEASE -->/d' \
       -e "s|(releases.k8s.io)/[^/]+|\1/${NEW_VERSION}|" \
       "${doc}"
+
+  # Replace /HEAD in html preview links with /NEW_VERSION.
+  $SED -ri -e "s|(${HTML_PREVIEW_PREFIX}/HEAD)|${HTML_PREVIEW_PREFIX}/${NEW_VERSION}|"
+
   is_versioned_tag='<!-- TAG IS_VERSIONED -->'
   if ! grep -q "${is_versioned_tag}" "${doc}"; then
     echo "${is_versioned_tag}" >> "${doc}"

diff --git a/docs/admin/node.md b/docs/admin/node.md
@@ -49,6 +49,7 @@ Documentation for other releases can be found at
     - [Self-Registration of nodes](#self-registration-of-nodes)
       - [Manual Node Administration](#manual-node-administration)
     - [Node capacity](#node-capacity)
+  - [API Object](#api-object)
 
 <!-- END MUNGE: GENERATED_TOC -->
 
@@ -247,6 +248,12 @@ Set the `cpu` and `memory` values to the amount of resources you want to reserve
 Place the file in the manifest directory (`--config=DIR` flag of kubelet).  Do this
 on each kubelet where you want to reserve resources.
 
+## API Object
+
+Node is a top-level resource in the kubernetes REST API. More details about the
+API object can be found at: [Node API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_node).
+
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/admin/node.md?pixel)]()

diff --git a/docs/user-guide/configuring-containers.md b/docs/user-guide/configuring-containers.md
@@ -108,6 +108,9 @@ pods/hello-world
 ```
 
 `kubectl create --validate` currently warns about problems it detects, but creates the resource anyway, unless a required field is absent or a field value is invalid. Unknown API fields are ignored, so be careful. This pod was created, but with no `command`, which is an optional field, since the image may specify an `Entrypoint`.
+View the [Pod API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_pod)
+to see the list of valid fields.
 
 ## Environment variables and variable expansion
 

diff --git a/docs/user-guide/connecting-applications.md b/docs/user-guide/connecting-applications.md
@@ -128,7 +128,8 @@ spec:
     app: nginx
 ```
 
-This specification will create a Service which targets TCP port 80 on any Pod with the `app=nginx` label, and expose it on an abstracted Service port (`targetPort`: is the port the container accepts traffic on, `port`: is the abstracted Service port, which can be any port other pods use to access the Service). Check your Service:
+This specification will create a Service which targets TCP port 80 on any Pod with the `app=nginx` label, and expose it on an abstracted Service port (`targetPort`: is the port the container accepts traffic on, `port`: is the abstracted Service port, which can be any port other pods use to access the Service). View [service API object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_service) to see the list of supported fields in service definition.
+Check your Service:
 
 ```console
 $ kubectl get svc

diff --git a/docs/user-guide/deploying-applications.md b/docs/user-guide/deploying-applications.md
@@ -75,6 +75,9 @@ spec:
 ```
 
 Some differences compared to specifying just a pod are that the `kind` is `ReplicationController`, the number of `replicas` desired is specified, and the pod specification is under the `template` field. The names of the pods don’t need to be specified explicitly because they are generated from the name of the replication controller.
+View the [replication controller API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_replicationcontroller)
+to view the list of supported fields.
 
 This replication controller can be created using `create`, just as with pods:
 

diff --git a/docs/user-guide/pods.md b/docs/user-guide/pods.md
@@ -110,6 +110,12 @@ Pod is exposed as a primitive in order to facilitate:
 
 The current best practice for pets is to create a replication controller with `replicas` equal to `1` and a corresponding service. If you find this cumbersome, please comment on [issue #260](https://github.com/GoogleCloudPlatform/kubernetes/issues/260). 
 
+## API Object
+
+Pod is a top-level resource in the kubernetes REST API. More details about the
+API object can be found at: [Pod API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_pod).
+
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/pods.md?pixel)]()

diff --git a/docs/user-guide/replication-controller.md b/docs/user-guide/replication-controller.md
@@ -47,6 +47,7 @@ Documentation for other releases can be found at
     - [Scaling](#scaling)
     - [Rolling updates](#rolling-updates)
     - [Multiple release tracks](#multiple-release-tracks)
+  - [API Object](#api-object)
 
 <!-- END MUNGE: GENERATED_TOC -->
 
@@ -117,6 +118,12 @@ In addition to running multiple releases of an application while a rolling updat
 
 For instance, a service might target all pods with `tier in (frontend), environment in (prod)`.  Now say you have 10 replicated pods that make up this tier.  But you want to be able to 'canary' a new version of this component.  You could set up a replication controller with `replicas` set to 9 for the bulk of the replicas, with labels `tier=frontend, environment=prod, track=stable`, and another replication controller with `replicas` set to 1 for the canary, with labels `tier=frontend, environment=prod, track=canary`.  Now the service is covering both the canary and non-canary pods.  But you can mess with the replication controllers separately to test things out, monitor the results, etc.
 
+## API Object
+
+Replication controller is a top-level resource in the kubernetes REST API. More details about the
+API object can be found at: [ReplicationController API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_replicationcontroller).
+
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/replication-controller.md?pixel)]()

diff --git a/docs/user-guide/services.md b/docs/user-guide/services.md
@@ -56,6 +56,7 @@ Documentation for other releases can be found at
   - [The gory details of virtual IPs](#the-gory-details-of-virtual-ips)
     - [Avoiding collisions](#avoiding-collisions)
     - [IPs and VIPs](#ips-and-vips)
+  - [API Object](#api-object)
 
 <!-- END MUNGE: GENERATED_TOC -->
 
@@ -526,6 +527,12 @@ of which `Pods` they are actually accessing.
 
 ![Services detailed diagram](services-detail.png)
 
+## API Object
+
+Service is a top-level resource in the kubernetes REST API. More details about the
+API object can be found at: [Service API
+object](https://htmlpreview.github.io/?https://github.com/GoogleCloudPlatform/kubernetes/HEAD/docs/api-reference/definitions.html#_v1_service).
+
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/services.md?pixel)]()