Skip to content

Commit

Permalink
Add support for custom notation type
Browse files Browse the repository at this point in the history
Add test files:
- Test custom overrides
- Test hyperlinks
- Test hyperlinks to value

Improvements:
- Add description about the hyperlinks
- Add more sample in the README.md
- Add support for multiline description sections
- Modify comment continuation regex
  • Loading branch information
lucernae authored May 6, 2022
1 parent 4b55b9e commit d2cc641
Show file tree
Hide file tree
Showing 13 changed files with 1,936 additions and 9 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,5 @@
dist
.idea/
*.iml
.vscode/
vendor/
3 changes: 3 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
helm-docs:
go build github.com/norwoodj/helm-docs/cmd/helm-docs

install:
go install github.com/norwoodj/helm-docs/cmd/helm-docs

.PHONY: fmt
fmt:
go fmt ./...
Expand Down
81 changes: 81 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,9 @@ can be used as well:
| chart.valuesHeader | The heading for the chart values section |
| chart.valuesTable | A table of the chart's values parsed from the `values.yaml` file (see below) |
| chart.valuesSection | A section headed by the valuesHeader from above containing the valuesTable from above or "" if there are no values |
| chart.valuesTableHtml | Like `chart.valuesTable` but it is rendered as (X)HTML tags to allow further rendering customization, instead of markdown tables format. |
| chart.valuesSectionHtml | Like `chart.valuesSection` but uses `chart.valuesTableHtml` |
| chart.valueDefaultColumnRender | This is a hook template if you want to redefine how helm-docs render the default values in `chart.valuesTableHtml` mode. This is especially useful when combined with (X)HTML tags, so that you can nicely format multiline default values, like YAML/JSON object tree snippet with codeblock syntax highlighter, which is not possible or difficult when using the markdown table format. It can be redefined in your template file. |

The default internal template mentioned above uses many of these and looks like this:
```
Expand Down Expand Up @@ -333,3 +336,81 @@ configMap:
# configMap."not real config param" -- A completely fake config parameter for a useful example
not real config param: value
```

### Advanced table rendering
Some helm chart `values.yaml` uses complicated structure for the key/value
pairs. For example, it may uses a multiline string of Go template text instead
of plain strings. Some values might also refer to a certain YAML/JSON object
structure, like internal k8s value type, or an enum. For these use case,
a standard markdown table format might be inadequate and you want to use HTML
tags to render the table.

Some example use case on why you need advanced table rendering:

- Hyperlinking the value type to an anchor or HTML link somewhere for reference
- Collapsible value description using `<summary>` tags to save space
- Multiline default values as codeblocks, instead of one line JSON structure for readability
- Custom rendering, for colors, actions, bookmarking, cross-reference, etc
- Cascading the markdown file generated by helm-docs to be post-processed by Jamstack into a static HTML docs site.

In order to accomodate this, `helm-docs` provides an extensible and flexible way to customize rendering.

1. Use the HTML value renderer instead of the default markdown format

You can use `chart.valuesSectionHtml` to render the values table as HTML tags,
instead of using `chart.valuesSection`. Using HTML tables provides more
flexibility because it can be processed by markdown viewer as a nested blocks,
instead of one row per line. This allows you to customize how each columns in a
row are rendered.

2. Overriding built-in templates

You can always overrides or redefine built-in templates in your own `_templates.
gotmpl` file. The built-in templates can be thought of as a template hook.
For example, if you need to change the HTML table, for example to add a new
column, or define maximum width/height, you can override `chart.valuesTableHtml`. Your overrides will then be called by `chart.valuesSectionHtml`.

You can add your own rendering logic for each column. For example, we have `chart.valueDefaultColumnRender` that is used to render "default value" column for each rows. If you want to override how helm-docs render the
"type" column, just define your own rendering template and call it from
`chart.valuesTableHtml` for each of the rows.

3. Using the metadata of each rows of values

Custom styling and rendering can be done as flexible as you want, but you
still need a metadata that describes each rows of values. You can access
this information from the templates.

When you override `chart.valuesTableHtml`, as you can see in the original
definition in `func getValuesTableTemplates()` [pkg/document/template.go](pkg/document/template.go), we iterates each row of values.
For each "Value", it is modeled as a struct defined in `valueRow` struct
in [pkg/document/model.go](pkg/document/model.go). You can then use the
fields in your template.

Some fields here are directly referenced from `values.yaml`:
- `Key`: the full name of the key referenced in `values.yaml`
- `Type`: the type of the value of the key in `values.yaml`. Can be automatically inferred from YAML structure, or annotated using `# -- (mytype)` where `mytype` can be any string that you refer as the type of the value.
- `NotationType`: the notation of the type used to render the default value. If `Type` refers to the data type of the value, then `NotationType` refers to **how** this value should be written/rendered by helm-docs. Generally helm-docs only remembers the notation type, but it was the writer's responsibility to make a template tag to render a specific notation type. Annotate the key with `# @notationType -- (mynotation)` where `mynotation` is an identifier to tell the renderer how to write the value.
- `Default`: this is the default value of the key, found from `values.yaml`. It is either inferred from the YAML structure or defined using `# @default -- my default value` annotation, in case you need to show other example values.
- `Description`: this is the description of the key/value, taken from the comments found in the `values.yaml` for the referred key.
- `LineNumber`: this is the line number associated with where the key is declared. You can use this to construct an anchor to the actual `values.yaml` file.

Note that helm-docs only provides these information, but the default behaviour is to always render it in plain Markdown file to be viewed locally.

4. Use markdown files generated by helm-docs as intermediary files to be processed further

Public helm charts sometimes needs to be published as static content
instead of just stored in a repository. This is needed for helm users to
be able to view or browse the chart options and dependencies.

It is often more than enough to just browse the chart values options on
git hosting that is able to render markdown files as a nice HTML page, like GitHub or GitLab.
However, for a certain use case, you may want to use your own
documentation generator to host or publish the output of helm-docs.

If you use some kind of Jamstack like Gatsby or Hugo, you can use the
output of helm-docs as an input for these doc generator. A typical use
case is to override helm-docs built-in template so that it renders a
markdown or markdownX files to be processed by Gatsby or Hugo into
a static Web/Javascript page.

For a more concrete examples on how to do these custom rendering, see [example here](./example-charts/custom-value-notation-type/README.md)
27 changes: 27 additions & 0 deletions example-charts/custom-value-notation-type/Chart.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
apiVersion: v2
name: django
version: 0.2.1
appVersion: 3.1
description: Generic chart for basic Django-based web app
keywords:
- Django
- Web
home: https://www.djangoproject.com/
sources:
- https://github.com/django/django
maintainers:
- name: Rizky Maulana Nugraha
email: [email protected]
icon: https://raw.githubusercontent.com/kartoza/charts/master/assets/logo/django.png
engine: gotpl
dependencies:
- name: postgis
version: 0.2.1
repository: "file://../../postgis/v0.2.1"
condition: postgis.enabled
tags:
- database-backend
- postgis
- name: common
version: 1.0.0
repository: "file://../../common/v1.0.0"
Loading

0 comments on commit d2cc641

Please sign in to comment.