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.
For an example output when running stella
for the
prometheus
helm chart, follow these links:
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]
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
usage: stella.py [-h] [-hcp HELM_CHART_PATH] [-o OUTPUT] [-t TEMPLATE] [-fh] [-ah] [-css CSS] [-v]
Will create documentation for helm charts using metadata.
options:
-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.
-ah, --advanced-html Output using html instead of md with additional features.
-css CSS, --css CSS Path to optional css file to use for html generation (use in conjunction with -fh).
-v, --verbose Activate debug logging.
The option --advanced-html
can't be used with custom CSS, as it offers some
additional functionality which would break when using custom CSS. It will
create a static html site with dynamic navbar and a search for the chart's
values.
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: |
podSecurityPolicy: |
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: |
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 }}
You want to contribute? Awesome! Feel free to propose changes, report bugs or request features and improvements. But first, please read the contribution guidelines.
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.