💫 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 these links:

• Advanced HTML (Deployed)
• Markdown (Source)
• Simple HTML (Source)

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] [-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.

⎈ 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.

🧑‍💻 Development

Expand for more info

Install GNU make to use the Makefile for easier handling of all necessary commands.

Linting Code

Install linters beforehand:

• markdownlint-cli
• ruff
• hadolint

# Markdown Linter
make markdownlint

# Python Linter
make ruff

# Dockerfile Linter
make hadolint

# Run all Linters at once
make lint

Running Unit Tests

make test

Updating Example Outputs

make examples