Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cert-manager/helm-tool
helm-tool is an internal cert-manager utility (can be broken or removed) which generates Helm docs, schema files and performs linting.
https://github.com/cert-manager/helm-tool
Last synced: 4 days ago
JSON representation
helm-tool is an internal cert-manager utility (can be broken or removed) which generates Helm docs, schema files and performs linting.
- Host: GitHub
- URL: https://github.com/cert-manager/helm-tool
- Owner: cert-manager
- License: apache-2.0
- Created: 2024-01-07T21:21:11.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-03-04T14:18:51.000Z (8 months ago)
- Last Synced: 2024-05-23T00:26:31.328Z (6 months ago)
- Language: Go
- Homepage:
- Size: 197 KB
- Stars: 2
- Watchers: 2
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Helm Docgen
Helm Docgen generates documentation for Helm charts by reading the values.yaml file. It works by reading the yaml content and the surrounding comments to infer information.
## Usage
There are two commands that can be used to generate documentation, `helm-tool render` and `helm-tool inject`.
- `helm-tool render` - The render command will simply render the markdown to the stdout
- `helm-tool inject` - The inject command will inject the generated documentation into an existing markdown file, it will look for the `## Properties` header and inject the documentation between it and the next header. This can be useful for keeping a chart README up to date.
## Customising the output
### Sections
Documentation can be divided up into sections through the `+docs:section` tag, for example:
```yaml
# +docs:section=Global
# This contains all parameters that are used by all deployments in this chart.
# Foo parameter description
foo: bar
# +docs:section=Application
# Application specific parameters
# Baz parameter description
baz: qux
```
Would produce the following markdown:
```markdown
### Global
This contains all parameters that are used by all deployments in this chart.
|property|description|type|default|
|--|--|--|--|
|`foo`|
Foo parameter description
|`string`|bar
|
### Application
Application specific parameters
|property|description|type|default|
|--|--|--|--|
|`baz`|
Baz parameter description
|`string`|qux
|
```
### Undefaulted properties
Often helm values files have properties that do not require a default value commented out, this tool can find those
by marking them with the `+docs:property` tag.
For example:
```yaml
# +docs:property
# Property description here
# foo: bar
```
Would produce the following markdown:
```markdown
|property|description|type|default|
|--|--|--|--|
|`foo`|
Property description here
|`string`|undefined
|
```
The detected name and type is not always correct, these can be provided using tags. For example:
```yaml
# +docs:property=foo
# +docs:type=string
# Property description here
```
```markdown
|property|description|type|default|
|--|--|--|--|
|`foo`|
Property description here
|`string`|undefined
|
```
### Tags
Tags are used to alter how the documentation is generated. They are comments that exist within a comment block
- `+docs:section=` - Creates a new documentation section
- `+docs:property` - Marks the field as a property that needs documentation
- `+docs:ignore` - Ignore the field, not generating documentation, not used for linting or json schema generation
- `+docs:hidden` - Hide the field from the documentation, but still use it for linting and json schema generation
- `+docs:type=` - Override the type information for the property
- `+docs:default=` - Override the default value for the property