💫 stella

stella is a free tool to help automatically generate helm chart documentation. It supports simple templating, so custom templates for output can be used as well. Will read metadata such as Chart.yaml, values.yaml or the present templates and generate a Markdown or HTML documentation from that data.

Example

For an example output when running stella for the prometheus helm chart, follow this link.

Usage

Docker Image

	Note
🐳	stella has switched from Docker Hub to ghcr.io. Please update all references to the new URI.

Using the Docker image:

docker pull ghcr.io/very-doge-wow/stella:latest
docker run -v ${full_path_to_host_chart_dir}:/tmp/chart ghcr.io/very-doge-wow/stella:latest -hcp /tmp/chart -o /tmp/chart/output.md [OPTIONS]

Installation

To run it natively on your machine using pipenv:

git clone https://github.com/very-doge-wow/stella.git
cd stella
pipenv install
pipenv run python stella.py --help

Alternatively install dependencies using pip:

git clone https://github.com/very-doge-wow/stella.git
cd stella
pip install pyyaml markdown
python stella.py --help

General Usage

usage: stella.py [-h] [-hcp HELM_CHART_PATH] [-o OUTPUT] [-t TEMPLATE] [-fh] [-css CSS] [-v]

Will create documentation for helm charts using metadata.

optional arguments:
  -h, --help            show this help message and exit
  -hcp HELM_CHART_PATH, --helm-chart-path HELM_CHART_PATH
                        Path to helm chart (default `.`).
  -o OUTPUT, --output OUTPUT
                        Output file (default `output.md`).
  -t TEMPLATE, --template TEMPLATE
                        Custom template file.
  -fh, --format-html    Output using html instead of md.
  -css CSS, --css CSS   Path to optional css file to use for html generation (use in conjunction with -fh).
  -v, --verbose         Activate debug logging.

Adding stella Docstrings to your Chart

Metadata is read from the present files of your chart. Additionally, you should also document the options given in your values.yaml. This can be done as follows:

# -- stella
# Define how many replicas should be deployed.
# -- example
# replicaCount: 2
replicaCount: 1

You can use multiline descriptions as well as multiline examples. In that case, the formatting of the example is preserved as is, meaning you can simply copy a working example and then prepend the comment delimiter (#).

The line starting with # -- stella tells stella that the following comment is a stella docstring. Use the # -- example delimiter to specify an optional example. If you leave this empty, the resulting documentation will leave this field blank. For example:

# -- stella
# Define whether to enable the pod security policy.
# -- example
# podSecurityPolicy:
#   enabled: true
podSecurityPolicy:
  enabled: false

Will yield the output:

Name	Description	Default	Example
podSecurityPolicy	Define whether to enable the pod security policy.	podSecurityPolicy: enabled: false	podSecurityPolicy: enabled: true

You may also document nested keys. For example:

configmapReload:
  # -- stella
  # URL for configmap-reload to use for reloads
  reloadUrl: ""

Will yield the output:

Name	Description	Default	Example
configmapReload.reloadUrl	URL for configmap-reload to use for reloads	configmapReload: reloadUrl: ''

Custom Templating

To specify a custom template, create a text/markdown file, then pass it to stella using the config parameter. You can use the following fields inside your template:

• {{ stella.name }}
• {{ stella.version }}
• {{ stella.appVersion }}
• {{ stella.apiVersion }}
• {{ stella.type }}
• {{ stella.description }}
• {{ stella.dependencies }}
• {{ stella.templates }}
• {{ stella.objects }}
• {{ stella.values }}

Contributing to stella

You want to contribute? Awesome! Feel free to propose changes, report bugs or request features and improvements. But first, please read the contribution guidelines.

Why stella?

stella is named after Tilemann Stella, a scholar from the Renaissance era. He is most famously known for being a cartographer and for creating multiple waterways, which is fitting when considering the tool should create helm chart docs.