Customizing your docs

Configuration descriptions

To set the descriptions of each configuration item you need to specify them as comments on the same row in your values.yaml file.

image:
  repository: nginx  # docker repository to pull the image from
  tag: stable  # image tag to use
  pullPolicy: IfNotPresent  # policy for kubernetes to use when pulling images

The above YAML would be rendered like this.

| Parameter                | Description             | Default        |
| ------------------------ | ----------------------- | -------------- |
| `image.repository` | Docker repository to pull the image from | `"nginx"` |
| `image.tag` | Image tag to use | `"stable"` |
| `image.pullPolicy` | Policy for kubernetes to use when pulling images | `"IfNotPresent"` |

Only comments on the same line as the option will be used.

# this comment will be ignored!
replicaCount: 1  # this comment will be used 🎉
# this comment will also be ignored!

Lists

Lists will take the comment from the same line as the key. The default value will be shown as a JSON string of the list.

env:  # environment variables
  - name: "USERNAME"
    value: "app-username"
| Parameter                | Description             | Default        |
| ------------------------ | ----------------------- | -------------- |
| `env` | Environment variables | `[{"name": "USERNAME", "value": "app-username"}]` |

Output formats

You can specify markdown, rst or html as output formats using the -o flag. See the command line reference for more info.

Templates

Frigate uses jinja2 templates to render your documentation.

As well as being able to specify various built in templates using the output formats flag you may also provide your own template all together.

To do this place a valid jinja2 template in your helm chart directory named .frigate. This template will then be used instead of any built in templates.

$ frigate gen hello-world

If the hello-world chart contains a .frigate template file this will be used automatically.

Available variables

Frigate exposes all of the options from within your chart’s Chart.yaml file as variables along with a list of tuples of all the configuration options called values.

For example you can access the name and version fields from your Chart.yaml.

{{ name }} - {{ version }}

Frigate makes use of most of the default fields from your Chart.yaml in it’s default templates, along with a few Frigate specific ones which you can optionally include.

  • long_description - A multiline description of your helm chart. Useful for including installation instructions and further information.

  • footnotes - A continuation of the long description to place below your table of configuration options. Useful for documenting things which are useful but not immediately important.

A simple .frigate template could be the following.

# {{ name }} - {{ version }}

{{ description }}

## Configuration options

{% for (param, comment, default) in values -%}
 - `{{ param }}` - {{ default }}
{% endfor -%}

This template is in markdown and would place your chart’s title and version in a top level header. Then include the description followed by a list of the configration options. It would output documentation like this.

# simple - 0.1.0

A Helm chart for Kubernetes

## Configuration options

- `replicaCount` - `1`
- `image.repository` - `"nginx"`
- `image.tag` - `"stable"`
- `image.pullPolicy` - `"IfNotPresent"`
- `imagePullSecrets` - `[]`
- `nameOverride` - `""`
- `fullnameOverride` - `""`
- `service.type` - `"ClusterIP"`
- `service.port` - `80`
- `ingress.enabled` - `false`
- `ingress.annotations` - `{}`
- `ingress.hosts` - `[{"host": "chart-example.local", "paths": []}]`
- `ingress.tls` - `[]`
- `resources` - `{}`
- `nodeSelector` - `{}`
- `tolerations` - `[]`
- `affinity` - `{}`

Extending built in templates

Instead of writing a whole template from scratch you are able to extend the built in charts. Specify the template you wish to extend and the blocks within the template that you wish to override.

{% extends "markdown.jinja2" %}

{% block title -%}
# {{ name | upper }}
{%- endblock %}

The above example would extend the markdown template and overrides the title block with an uppercase title.

Templates available to extend:

  • markdown.jinja2 - Markdown template

  • rst.jinja2 - reStructuredText template

  • html.jinja2 - HTML template

  • base.jinja2 - Base blank template with no content

Blocks available for overriding:

  • header - Misc block for the top of the document

  • title - The title of the page

  • description - The description of the chart

  • table - The table of configuration options

  • footnotes - Additional description to go below the table

  • credits - Crediting the generation of the document to Frigate

  • footer - Misc block for the bottom of the document