From 0166a0b08e804e572349665fc1ce1a425c5246ed Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Tue, 12 Jan 2021 17:20:33 -0500 Subject: [PATCH] add docs for version shortcodes --- .../en/docs/concepts/architecture/nodes.md | 2 +- .../en/docs/concepts/configuration/secret.md | 2 +- .../en/docs/concepts/workloads/pods/_index.md | 16 +-- .../style/hugo-shortcodes/example1.md | 2 +- .../contribute/style/hugo-shortcodes/index.md | 127 ++++++++++-------- .../reference/using-api/server-side-apply.md | 2 +- 6 files changed, 83 insertions(+), 68 deletions(-) diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index a9abf48856..7bd4b355b6 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -242,7 +242,7 @@ checks the state of each node every `--node-monitor-period` seconds. Heartbeats, sent by Kubernetes nodes, help determine the availability of a node. There are two forms of heartbeats: updates of `NodeStatus` and the -[Lease object](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/#lease-v1-coordination-k8s-io). +[Lease object](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#lease-v1-coordination-k8s-io). Each Node has an associated Lease object in the `kube-node-lease` {{< glossary_tooltip term_id="namespace" text="namespace">}}. Lease is a lightweight resource, which improves the performance diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md index 3674c3ce4c..fbaf0c1a29 100644 --- a/content/en/docs/concepts/configuration/secret.md +++ b/content/en/docs/concepts/configuration/secret.md @@ -776,7 +776,7 @@ these pods. The `imagePullSecrets` field is a list of references to secrets in the same namespace. You can use an `imagePullSecrets` to pass a secret that contains a Docker (or other) image registry password to the kubelet. The kubelet uses this information to pull a private image on behalf of your Pod. -See the [PodSpec API](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/#podspec-v1-core) for more information about the `imagePullSecrets` field. +See the [PodSpec API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core) for more information about the `imagePullSecrets` field. #### Manually specifying an imagePullSecret diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md index af548a79cb..5dd6bac9de 100644 --- a/content/en/docs/concepts/workloads/pods/_index.md +++ b/content/en/docs/concepts/workloads/pods/_index.md @@ -15,8 +15,7 @@ card: _Pods_ are the smallest deployable units of computing that you can create and manage in Kubernetes. A _Pod_ (as in a pod of whales or pea pod) is a group of one or more -{{< glossary_tooltip text="containers" term_id="container" >}}, with shared storage/network resources, and a specification -for how to run the containers. A Pod's contents are always co-located and +{{< glossary_tooltip text="containers" term_id="container" >}}, with shared storage and network resources, and a specification for how to run the containers. A Pod's contents are always co-located and co-scheduled, and run in a shared context. A Pod models an application-specific "logical host": it contains one or more application containers which are relatively tightly coupled. @@ -295,9 +294,10 @@ but cannot be controlled from there. object definition describes the object in detail. * [The Distributed System Toolkit: Patterns for Composite Containers](https://kubernetes.io/blog/2015/06/the-distributed-system-toolkit-patterns) explains common layouts for Pods with more than one container. -To understand the context for why Kubernetes wraps a common Pod API in other resources (such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or {{< glossary_tooltip text="Deployments" term_id="deployment" >}}, you can read about the prior art, including: - * [Aurora](https://aurora.apache.org/documentation/latest/reference/configuration/#job-schema) - * [Borg](https://research.google.com/pubs/pub43438.html) - * [Marathon](https://mesosphere.github.io/marathon/docs/rest-api.html) - * [Omega](https://research.google/pubs/pub41684/) - * [Tupperware](https://engineering.fb.com/data-center-engineering/tupperware/). +To understand the context for why Kubernetes wraps a common Pod API in other resources (such as {{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}} or {{< glossary_tooltip text="Deployments" term_id="deployment" >}}), you can read about the prior art, including: + +* [Aurora](https://aurora.apache.org/documentation/latest/reference/configuration/#job-schema) +* [Borg](https://research.google.com/pubs/pub43438.html) +* [Marathon](https://mesosphere.github.io/marathon/docs/rest-api.html) +* [Omega](https://research.google/pubs/pub41684/) +* [Tupperware](https://engineering.fb.com/data-center-engineering/tupperware/). diff --git a/content/en/docs/contribute/style/hugo-shortcodes/example1.md b/content/en/docs/contribute/style/hugo-shortcodes/example1.md index fbe21a1457..9e9f45b0a6 100644 --- a/content/en/docs/contribute/style/hugo-shortcodes/example1.md +++ b/content/en/docs/contribute/style/hugo-shortcodes/example1.md @@ -6,4 +6,4 @@ This is an **example** content file inside the **includes** leaf bundle. {{< note >}} Included content files can also contain shortcodes. -{{< /note >}} \ No newline at end of file +{{< /note >}} diff --git a/content/en/docs/contribute/style/hugo-shortcodes/index.md b/content/en/docs/contribute/style/hugo-shortcodes/index.md index dd9ed06c31..fa25966e45 100644 --- a/content/en/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/en/docs/contribute/style/hugo-shortcodes/index.md @@ -1,33 +1,30 @@ --- -approvers: -- chenopis title: Custom Hugo Shortcodes content_type: concept --- -This page explains the custom Hugo shortcodes that can be used in Kubernetes markdown documentation. +This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation. Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes). - ## Feature state -In a markdown page (`.md` file) on this site, you can add a shortcode to display version and state of the documented feature. +In a Markdown page (`.md` file) on this site, you can add a shortcode to display version and state of the documented feature. ### Feature state demo -Below is a demo of the feature state snippet, which displays the feature as stable in Kubernetes version 1.10. +Below is a demo of the feature state snippet, which displays the feature as stable in the latest Kubernetes version. ``` -{{}} +{{}} ``` Renders to: -{{< feature-state for_k8s_version="v1.10" state="stable" >}} +{{< feature-state state="stable" >}} The valid values for `state` are: @@ -38,62 +35,22 @@ The valid values for `state` are: ### Feature state code -The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the for_k8s_version shortcode parameter. +The displayed Kubernetes version defaults to that of the page or the site. You can change the +feature state version by passing the `for_k8s_version` shortcode parameter. For example: ``` -{{}} +{{}} ``` Renders to: -{{< feature-state for_k8s_version="v1.10" state="stable" >}} - -#### Alpha feature - -``` -{{}} -``` - -Renders to: - -{{< feature-state state="alpha" >}} - -#### Beta feature - -``` -{{}} -``` - -Renders to: - -{{< feature-state state="beta" >}} - -#### Stable feature - -``` -{{}} -``` - -Renders to: - -{{< feature-state state="stable" >}} - -#### Deprecated feature - -``` -{{}} -``` - -Renders to: - -{{< feature-state state="deprecated" >}} +{{< feature-state for_k8s_version="v1.10" state="beta" >}} ## Glossary -There are two glossary tooltips. +There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`. -You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone -using the online documentation, the glossary entry displays a tooltip. +You can reference glossary terms with an inclusion that automatically updates and replaces content with the relevant links from [our glossary](/docs/reference/glossary/). When the glossary term is moused-over, the glossary entry displays a tooltip. The glossary term also displays as a link. As well as inclusions with tooltips, you can reuse the definitions from the glossary in page content. @@ -102,7 +59,7 @@ The raw data for glossary terms is stored at [https://github.com/kubernetes/webs ### Glossary demo -For example, the following include within the markdown renders to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: +For example, the following include within the Markdown renders to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: ``` {{}} @@ -113,13 +70,16 @@ Here's a short glossary definition: ``` {{}} ``` + which renders as: {{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}} You can also include a full definition: + ``` {{}} ``` + which renders as: {{< glossary_definition term_id="cluster" length="all" >}} @@ -255,7 +215,63 @@ Renders to: {{< tab name="JSON File" include="podtemplate.json" />}} {{< /tabs >}} +## Version strings +To generate a version string for inclusion in the documentation, you can choose from +several version shortcodes. Each version shortcode displays a version string derived from +the value of a version parameter found in the site configuration file, `config.toml`. +The two most commonly used version parameters are `latest` and `version`. + +### `{{}}` + +The `{{}}` shortcode generates the value of the current version of +the Kubernetes documentation from the `version` site parameter. The `param` shortcode accepts the name of one site parameter, in this case: `version`. + +{{< note >}} +In previously released documentation, `latest` and `version` parameter values are not equivalent. +After a new version is released, `latest` is incremented and the value of `version` for the documentation set remains unchanged. For example, a previously released version of the documentation displays `version` as +`v1.19` and `latest` as `v1.20`. +{{< /note >}} + +Renders to: + +{{< param "version" >}} + +### `{{}}` + +The `{{}}` shortcode returns the value of the `latest` site parameter. +The `latest` site parameter is updated when a new version of the documentation is released. +This parameter does not always match the value of `version` in a documentation set. + +Renders to: + +{{< latest-version >}} + +### `{{}}` + +The `{{}}` shortcode generates the value of `latest` without the "v" prefix. + +Renders to: + +{{< latest-semver >}} + +### `{{}}` + +The `{{}}` shortcode checks if the `min-kubernetes-server-version` +page parameter is present and then uses this value to compare to `version`. + +Renders to: + +{{< version-check >}} + +### `{{}}` + +The `{{}}` shortcode generates a version string from `latest` and removes +the "v" prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified version string. + +Renders to: + +{{< latest-release-notes >}} ## {{% heading "whatsnext" %}} @@ -264,4 +280,3 @@ Renders to: * Learn about [page content types](/docs/contribute/style/page-content-types/). * Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/). * Learn about [advanced contributing](/docs/contribute/advanced/). - diff --git a/content/en/docs/reference/using-api/server-side-apply.md b/content/en/docs/reference/using-api/server-side-apply.md index c945765d76..c281eb9400 100644 --- a/content/en/docs/reference/using-api/server-side-apply.md +++ b/content/en/docs/reference/using-api/server-side-apply.md @@ -71,7 +71,7 @@ the appliers, results in a conflict. Shared field owners may give up ownership of a field by removing it from their configuration. Field management is stored in a`managedFields` field that is part of an object's -[`metadata`](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/#objectmeta-v1-meta). +[`metadata`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta). A simple example of an object created by Server Side Apply could look like this: