docs: use nindent in documentation examples (#4905)

* docs: markdown prettyprinting Signed-off-by: Geoff Baskwill <me@geoffbaskwill.ca> * docs: use nindent in documentation examples Fixes #4890. Signed-off-by: Geoff Baskwill <me@geoffbaskwill.ca>
6 years ago · 560b84d53c
parent 5df2c584ce
commit 560b84d53c
3 changed files with 42 additions and 32 deletions
--- a/docs/chart_template_guide/accessing_files.md
+++ b/docs/chart_template_guide/accessing_files.md
@ -6,8 +6,8 @@ Helm provides access to files through the `.Files` object. Before we get going w

 - It is okay to add extra files to your Helm chart. These files will be bundled and sent to Tiller. Be careful, though. Charts must be smaller than 1M because of the storage limitations of Kubernetes objects.
 - Some files cannot be accessed through the `.Files` object, usually for security reasons.
-	- Files in `templates/` cannot be accessed.
-	- Files excluded using `.helmignore` cannot be accessed.
+  - Files in `templates/` cannot be accessed.
+  - Files excluded using `.helmignore` cannot be accessed.
 - Charts do not preserve UNIX mode information, so file-level permissions will have no impact on the availability of a file when it comes to the `.Files` object.

 <!-- (see https://github.com/jonschlinkert/markdown-toc) -->
@ -90,6 +90,7 @@ use. They are all accessible with the same names as in the Go package, but
 with a lowercase first letter. For example, `Base` becomes `base`, etc.

 The imported functions are:
+
 - Base
 - Dir
 - Ext
@ -107,7 +108,7 @@ the returned object.

 For example, imagine the directory structure:

-```
+```txt
 foo/:
  foo.txt foo.yaml

@ -117,7 +118,6 @@ bar/:

 You have multiple options with Globs:

-
 ```yaml
 {{ $root := . }}
 {{ range $path, $bytes := .Files.Glob "**.yaml" }}
@ -153,7 +153,7 @@ kind: ConfigMap
 metadata:
  name: conf
 data:
-{{ (.Files.Glob "foo/*").AsConfig | indent 2 }}
+  {{- (.Files.Glob "foo/*").AsConfig | nindent 2 }}
 ---
 apiVersion: v1
 kind: Secret
@ -161,7 +161,7 @@ metadata:
  name: very-secret
 type: Opaque
 data:
-{{ (.Files.Glob "bar/*").AsSecrets | indent 2 }}
+  {{- (.Files.Glob "bar/*").AsSecrets | nindent 2 }}
 ```

 ## Encoding
@ -207,4 +207,3 @@ data:
 Currently, there is no way to pass files external to the chart during `helm install`. So if you are asking users to supply data, it must be loaded using `helm install -f` or `helm install --set`.

 This discussion wraps up our dive into the tools and techniques for writing Helm templates. In the next section we will see how you can use one special file, `templates/NOTES.txt`, to send post-installation instructions to the users of your chart.
-
--- a/docs/chart_template_guide/named_templates.md
+++ b/docs/chart_template_guide/named_templates.md
@ -14,9 +14,9 @@ So far, we've used one file, and that one file has contained a single template.

 Before we get to the nuts-and-bolts of writing those templates, there is file naming convention that deserves mention:

-* Most files in `templates/` are treated as if they contain Kubernetes manifests
-* The `NOTES.txt` is one exception
-* But files whose name begins with an underscore (`_`) are assumed to _not_ have a manifest inside. These files are not rendered to Kubernetes object definitions, but are available everywhere within other chart templates for use.
+- Most files in `templates/` are treated as if they contain Kubernetes manifests
+- The `NOTES.txt` is one exception
+- But files whose name begins with an underscore (`_`) are assumed to _not_ have a manifest inside. These files are not rendered to Kubernetes object definitions, but are available everywhere within other chart templates for use.

 These files are used to store partials and helpers. In fact, when we first created `mychart`, we saw a file called `_helpers.tpl`. That file is the default location for template partials.

@ -139,7 +139,7 @@ metadata:

 What happened to the name and version? They weren't in the scope for our defined template. When a named template (created with `define`) is rendered, it will receive the scope passed in by the `template` call. In our example, we included the template like this:

-```yaml
+```gotpl
 {{- template "mychart.labels" }}
 ```

@ -223,7 +223,7 @@ Note that the indentation on `app_version` is wrong in both places. Why? Because

 To work around this case, Helm provides an alternative to `template` that will import the contents of a template into the present pipeline where it can be passed along to other functions in the pipeline.

-Here's the example above, corrected to use `indent` to indent the `mychart_app` template correctly:
+Here's the example above, corrected to use `nindent` to indent the `mychart_app` template correctly:

 ```yaml
 apiVersion: v1
@ -231,13 +231,13 @@ kind: ConfigMap
 metadata:
  name: {{ .Release.Name }}-configmap
  labels:
-{{ include "mychart.app" . | indent 4 }}
+    {{- include "mychart.app" . | nindent 4 }}
 data:
  myvalue: "Hello World"
  {{- range $key, $val := .Values.favorite }}
  {{ $key }}: {{ $val | quote }}
  {{- end }}
-{{ include "mychart.app" . | indent 2 }}
+  {{- include "mychart.app" . | nindent 2 }}
 ```

 Now the produced YAML is correctly indented for each section:
--- a/docs/charts_tips_and_tricks.md
+++ b/docs/charts_tips_and_tricks.md
@ -22,18 +22,18 @@ For example, this template snippet includes a template called `mytpl`, then
 lowercases the result, then wraps that in double quotes.

 ```yaml
-value: {{include "mytpl" . | lower | quote}}
+value: {{ include "mytpl" . | lower | quote }}
 ```

 The `required` function allows you to declare a particular
-values entry as required for template rendering.  If the value is empty, the template
+values entry as required for template rendering. If the value is empty, the template
 rendering will fail with a user submitted error message.

 The following example of the `required` function declares an entry for .Values.who
 is required, and will print an error message when that entry is missing:

 ```yaml
-value: {{required "A valid .Values.who entry required!" .Values.who }}
+value: {{ required "A valid .Values.who entry required!" .Values.who }}
 ```

 ## Quote Strings, Don't Quote Integers
@ -41,20 +41,20 @@ value: {{required "A valid .Values.who entry required!" .Values.who }}
 When you are working with string data, you are always safer quoting the
 strings than leaving them as bare words:

-```
-name: {{.Values.MyName | quote }}
+```yaml
+name: {{ .Values.MyName | quote }}
 ```

 But when working with integers _do not quote the values._ That can, in
 many cases, cause parsing errors inside of Kubernetes.

-```
+```yaml
 port: {{ .Values.Port }}
 ```

 This remark does not apply to env variables values which are expected to be string, even if they represent integers:

-```
+```yaml
 env:
  -name: HOST
    value: "http://host"
@ -71,12 +71,16 @@ Go template pipelines.
 To make it possible to include a template, and then perform an operation
 on that template's output, Helm has a special `include` function:

-```
-{{ include "toYaml" $value | indent 2 }}
+```gotpl
+{{- include "toYaml" $value | nindent 2 }}
 ```

 The above includes a template called `toYaml`, passes it `$value`, and
-then passes the output of that template to the `indent` function.
+then passes the output of that template to the `nindent` function. Using
+the `{{- ... | nindent _n_ }}` pattern makes it easier to read the `include`
+in context, because it chomps the whitespace to the left (including the
+previous newline), then the `nindent` re-adds the newline and indents
+the included content by the requested amount.

 Because YAML ascribes significance to indentation levels and whitespace,
 this is one great way to include snippets of code, but handle
@ -99,7 +103,7 @@ developer.

 For example:

-```
+```gotpl
 {{ required "A valid foo is required!" .Values.foo }}
 ```

@ -113,7 +117,8 @@ This is useful to pass a template string as a value to a chart or render externa
 Syntax: `{{ tpl TEMPLATE_STRING VALUES }}`

 Examples:
-```
+
+```yaml
 # values
 template: "{{ .Values.name }}"
 name: "Tom"
@ -126,7 +131,8 @@ Tom
 ```

 Rendering a external configuration file:
-```
+
+```yaml
 # external configuration file conf/app.conf
 firstName={{ .Values.firstName }}
 lastName={{ .Values.lastName }}
@ -144,10 +150,12 @@ lastName=Parker
 ```

 ## Creating Image Pull Secrets
-Image pull secrets are essentially a combination of _registry_, _username_, and _password_.  You may need them in an application you are deploying, but to create them requires running _base64_ a couple of times.  We can write a helper template to compose the Docker configuration file for use as the Secret's payload.  Here is an example:
+
+Image pull secrets are essentially a combination of _registry_, _username_, and _password_. You may need them in an application you are deploying, but to create them requires running _base64_ a couple of times. We can write a helper template to compose the Docker configuration file for use as the Secret's payload. Here is an example:

 First, assume that the credentials are defined in the `values.yaml` file like so:
-```
+
+```yaml
 imageCredentials:
  registry: quay.io
  username: someone
@ -155,14 +163,16 @@ imageCredentials:
 ```

 We then define our helper template as follows:
-```
+
+```gotpl
 {{- define "imagePullSecret" }}
 {{- printf "{\"auths\": {\"%s\": {\"auth\": \"%s\"}}}" .Values.imageCredentials.registry (printf "%s:%s" .Values.imageCredentials.username .Values.imageCredentials.password | b64enc) | b64enc }}
 {{- end }}
 ```

 Finally, we use the helper template in a larger template to create the Secret manifest:
-```
+
+```yaml
 apiVersion: v1
 kind: Secret
 metadata:
@ -282,6 +292,7 @@ update of that resource.
 ## Upgrade a release idempotently

 In order to use the same command when installing and upgrading a release, use the following command:
+
 ```shell
 helm upgrade --install <release name> --values <values file> <chart directory>
 ```