Auto generate README.md, Chart.yaml, values.schema.json and values.yaml using tem & helm-jsonschema-gen

[inteon]

What this PR does / why we need it:
Alternative implementation for solving #4199.
It uses a tool called tem, that I created.
tem combines the functionality of kubepack.dev/chart-doc-gen and github.com/gomatic/renderizer/v2.
It also allows us to create custom table layouts.
tem does not ONLY work for Helm, it can be used for any situation where templating using YAML as input is useful.

UPDATE: as requested by @wallrj, now the values.schema.json file is also auto-generated.
This is done using another custom tool https://github.com/amurant/helm-jsonschema-gen, that uses go code and
translates it to a JSON schema definition.

Which issue this PR fixes

fixes #4010
fixes #2891

Release note:

The Helm chart README.md, Chart.yaml, values.yaml, values.schema.json files are now generated automatically

[jetstack-bot]

Hi @inteon. Thanks for your PR.

I'm waiting for a jetstack or cert-manager member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[irbekrm]

/ok-to-test

[wallrj]

Thanks @inteon

tem seems really cool. Useful to be able to apply Helm style templating generally, plus the added parsing of comments.
I haven't reviewed the code though.

I've got some general questions about this approach:

1. If we agree that we can improve the installation experience by creating a Helm JSON schema, which will help prevent users from setting invalid values. Then the json schema file seems like the natural place to add value descriptions (rather than in comments in the Yaml). And json schema supports examples and defaults annotations too which would make those things much easier to extract and avoid parsing the comment strings. https://json-schema.org/understanding-json-schema/reference/generic.html#annotations
2. And I had a vague idea that the JSON schema file might serve as the basis for generating command line flags that reflect the available values, e.g. kubectl cert-manager install --cainjector.enabled=false --controller.resources.requests.memory=200Mi.
3. Or it could be used to generate an overview of the available values in kubectl cert-manager install --help.
4. The generated README file in this branch creates a table which scrolls horizontally, way beyond the page margin, which makes it very difficult to read: https://github.com/jetstack/cert-manager/blob/2026972af9a74d62dd0adcce99b9c90e0cf43534/deploy/charts/cert-manager/README.md#configurationThe original table has wrapped cell content: https://github.com/jetstack/cert-manager/blob/master/deploy/charts/cert-manager/README.template.md#configuration
5. I dislike the complicated template logic in README.template.md which is used to create the table of values. I find it difficult to interpret. Isn't there a markdown generator which can take a slice of structs and turn it into a table?
6. If tem is used, can it not be downloaded as a binary rather than adding its Go dependencies to those of cert-manager, which are already too sprawling.

Please pick holes these arguments if you disagree.

[inteon]

1. & 2) I agree that ideally cert-manager should have a json-schema added to its chart. I fear however, that it will be very hard to manage such a schema directly. Charts that use this schema often only use it to partially describe the values.yaml file.
   eg. https://github.com/bitnami/charts/blob/master/bitnami/redis/values.yaml vs https://github.com/bitnami/charts/blob/master/bitnami/redis/values.schema.json

2. kubectl cert-manager install --help -> Yes, we should add more info to the install command. This can be done by using json-schema OR just the values.yaml file. json-schema could add some validation, but might be harder to maintain (see 1&2)

3. That version contained an error that removed the newlines. Somehow, github accepts <br> as a newline only if the "lang" attribute of the surrounding <pre> tag is not set.
   The latest version should be rendered better:
   https://github.com/jetstack/cert-manager/blob/e9ed8426b8b6d92a6217ed0efc6dcdc6799620a7/deploy/charts/cert-manager/README.md

4. This is the best way I have found to make the table-generation more modular. This allows cert-manager to specify custom logic for rendering the comments above a values.yaml property. Most of this logic is related to rendering the yaml examples and using the correct characters in the table. https://github.com/kubepack/chart-doc-gen hardcodes this, but that means that in some situations it might not work eg. Show multi-value lines inside <code> block #31 kubepack/chart-doc-gen#32.

5. fixed

[wallrj]

Thanks for downloading the binaries and making the darwin binaries available.

I'm still in favour of using the jsonschema as the source of all this information...I think it could even be used to generate the values.yaml file.

ArtifactHub does a pretty nice job of presenting the schema: https://artifacthub.io/packages/helm/bitnami/redis?modal=values-schema

Which makes me think we could even drop the table of values from the README.

Let's discuss it tomorrow.

[wallrj]

I'm just going to leave this here: https://github.com/coveooss/json-schema-for-humans/blob/master/docs/examples/examples_md_default/Configuration.md

[inteon]

blocked on #4556

[inteon]

blocked on improvements to the dependencies. (I'm working on helm-jsonschema-gen and tem improvements)

[jetstack-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to jetstack.
/lifecycle stale

[jetstack-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to jetstack.
/lifecycle stale

[inteon]

/remove-lifecycle stale

[jetstack-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: inteon, wallrj

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [inteon,wallrj]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[jetstack-bot]

@inteon: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-cert-manager-bazel	3100f34	link	/test pull-cert-manager-bazel
pull-cert-manager-master-chart	3100f34	link	true	/test pull-cert-manager-master-chart
pull-cert-manager-master-make-test	3100f34	link	true	/test pull-cert-manager-master-make-test
pull-cert-manager-master-e2e-v1-24	3100f34	link	true	/test pull-cert-manager-master-e2e-v1-24
pull-cert-manager-master-e2e-v1-25	3100f34	link	true	/test pull-cert-manager-master-e2e-v1-25
pull-cert-manager-master-e2e-v1-24-upgrade	3100f34	link	true	/test pull-cert-manager-master-e2e-v1-24-upgrade
pull-cert-manager-master-e2e-v1-25-upgrade	3100f34	link	true	/test pull-cert-manager-master-e2e-v1-25-upgrade
pull-cert-manager-master-e2e-v1-26-upgrade	d00da3c	link	true	/test pull-cert-manager-master-e2e-v1-26-upgrade

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

[inteon]

will pick this up later in another PR