Introducing Frigate

A documentation generation tool for Kubernetes Helm Charts

With more people building and running their workloads on Kubernetes it has become a standard requirement that projects like RAPIDS package software in Helm Charts to enable quick and easy installation on user’s clusters.

When publishing a Helm Chart it has become the defacto standard to include a table of all the configuration options from the Chart’s values.yaml file with descriptions of each item and the default value if one exists.

Maintaining a table like this is fantastic for the user’s to be able to quickly understand the configuration options available to them, but it adds an additional overhead on developers as any changes to the values.yaml need to be reflected in the documentation.

That’s where Frigate comes in. Frigate is a simple tool which will read in the values.yaml file and also the Chart.yaml file from a Helm Chart and automatically generate a documentation page for you.

Quick Start

Install Frigate using pip.

$ pip install frigate

Run frigate gen with the path to your Helm Chart.

$ frigate gen path/to/chart

Generated documentation will be written to stdout.

A common use case may be to automatically generate your README.md file from your Helm Chart, either manually or as part of an automated action.

$ frigate gen path/to/chart > path/to/README.md

Overview

There are three default templates available which allow you to generate a documentation file in markdown, reStructuredText, or HTML (with markdown being the default). You can select a template with the --output-format flag.

Each template starts by reading the name and description properties from the Chart.yaml file, and laying them out at the top of the page. It will then also read an optional long_description property, which is not part of the Helm Chart spec but is an optional extra for use by Frigate.

Example of the rapidsai Helm Chart’s Chart.yaml next to the Frigate generated README.md.

Next, a table of all configuration items from values.yaml will be rendered with the default values detected automatically. Any inline comments from the YAML will also be included in the description column of the table.

Example of a values.yaml file next to a Frigate generated README.md.

The default templates also include a footnotes section if you want to be able to add more documentation after the configuration table. This will be read from a footnotes property from the Chart.yaml file.

Example of including footnotes.

Extensibility

You are also not limited to using the default templates included in Frigate.

If you include a template file named .frigate in your Helm Chart, this will be used instead. Frigate uses the Jinja2 templating language, so it is possible to override specific blocks from the default templates, or write your own from scratch using all of the properties available in your values.yaml and Chart.yaml files.

An example of a custom .friagte template from the Frigate tests.

Sphinx

As well as generating documentation to stdout Frigate can also be used as an extension in Sphinx documentation sites.

To get started, install frigate as normal, and add the Frigate extension to your Sphinx conf.py file.

extensions = ["frigate.sphinx.ext"]

Then in your documentation pages you can use the Frigate directive to render your documentation inline on the page.

.. frigate:: path/to/your/helm/chart

As Sphinx primarily uses reStructuredText it will default to the rst template.

What’s Next

Frigate was built to automate the generation of Helm Chart documentation for RAPIDS and the rest of the PyData community.

If Frigate is useful to you, or there are any features you would like to see in it we would love to hear from you. Contributions are very welcome!

For more information check out the documentation.