Helm doc generation

[DoGab]

Idea

Might be a good idea to use a helm documentation generator to render the values.yaml file into a easy to read table in the README

Tools

2 tools that could be used to achieve the goal. Both tools have the possiblity to provide a README template file in which the table containing the values is rendered into.

• Chart-doc-gen
• Helm-docs

[jessebot]

It would be great to have official docs on all the available parameters for this helm chart.

I like helm-docs and the neat thing about helm-docs is that you can add it as a pre-commit hook by creating a file in the root of your repo called .pre-commit-config.yaml with the following:

repos:
  # update the chart README.md with the comments from values.yaml
  - repo: https://github.com/norwoodj/helm-docs
    rev: v1.2.0
    hooks:
      - id: helm-docs
  # helm lint - this is extra just for linting, but also helpful
  - repo: https://github.com/gruntwork-io/pre-commit
    rev: v0.1.22 # Get the latest from: https://github.com/gruntwork-io/pre-commit/releases
    hooks:
      - id: helmlint

Then, in your CONTRIBUTING.md you can ask that people run the following before starting work on a fix/feature branch:

pre-commit install

Then when someone updates the values.yaml with a new value like this:

$ git diff values.yaml
diff --git a/charts/matrix/values.yaml b/charts/matrix/values.yaml
index 2437c00..705fc0e 100644
--- a/charts/matrix/values.yaml
+++ b/charts/matrix/values.yaml
@@ -16,6 +16,9 @@ matrix:
   # in the fediverse, & will be the domain name at the end of every username
   serverName: "example.com"

+  # -- new value doc
+  new_value: "test"
+
   # -- Enable anonymous telemetry to matrix.org
   telemetry: false

And they try to commit, they'll get this:

$ git commit -m "test commit"
Helm Docs................................................................Failed
- hook id: helm-docs
- files were modified by this hook

INFO[2023-08-20T12:38:20+02:00] Found Chart directories [charts/matrix]
INFO[2023-08-20T12:38:20+02:00] Generating README Documentation for chart charts/matrix

helmlint.................................................................Passed
Detect hardcoded secrets.................................................Passed

and it will update the docs like this:

$ git diff
diff --git a/charts/matrix/README.md b/charts/matrix/README.md
index 654ea7e..6948d85 100644
--- a/charts/matrix/README.md
+++ b/charts/matrix/README.md
@@ -231,6 +231,7 @@ A Helm chart to deploy a Matrix homeserver stack into Kubernetes
 | matrix.logging.rootLogLevel | string | `"WARNING"` | Root log level is the default log level for log outputs that don't have more specific settings. |
 | matrix.logging.sqlLogLevel | string | `"WARNING"` | beware: increasing this to DEBUG will make synapse log sensitive information such as access tokens. |
 | matrix.logging.synapseLogLevel | string | `"WARNING"` | The log level for the synapse server |
+| matrix.new_value | string | `"test"` | new value doc |
 | matrix.oidc_config.authorization_endpoint | string | `"https://accounts.example.com/oauth2/auth"` | oauth2 authorization endpoint. Required if provider discovery disabled. |
 | matrix.oidc_config.client_auth_method | string | `"client_secret_post"` | auth method to use when exchanging the token. Valid values are: 'client_secret_basic' (default), 'client_secret_post' and 'none'. |
 | matrix.oidc_config.client_id | string | `"provided-by-your-issuer"` | oauth2 client id to use. Required if 'enabled' is true. |

I haven't used chart-doc-gen, but I'll have to try it!