Auto-generate CRD docs and manifests

[ableuler]

This PR renders the helm chart into static manifests using a pre-commit hook and uses a github action to auto-generate a clickable markdown documentation of the custom resource. The manifests should probably be created in an action too instead of using the git hook...?

[olevski]

One minor thing...

[ableuler]

Ok, after some forth-and-back, learning a bit more about actions in general and also toying with kustomize, here's the overhauled version of this PR and what it does:

• It adds a /manifests directory with all the rendered manifests and a very basic kustomization file which can serve as base for real-world kustomization.
• It adds a /docs/crd.md file which is a clickable documentation of the custom resource definition
• It adds a .github/workflows/generate-crd-docs.yaml workflow which is triggered after every push to main. It automatically builds the content of /manifests and /docs/crd.yaml and opens a PR if any of these are found to be outdated. The action also pushes an image tagged with both latest and the current git commit hash. This is to make sure that the latest image is really the latest image as we are referring to it in /manifests/deployment.yaml.

[ableuler]

Note: To test I did some small edit to the crd.yaml and manually triggered the generate-crd-docs.yaml workflow on this PR branch (normally it would only run on main). This is the resulting run https://github.com/SwissDataScienceCenter/amalthea/runs/3684285085?check_suite_focus=true, which opened this PR as intended: #89

[rokroskar]

I'm coming to this a bit late, but is there a reason not to have actual docs for amalthea on readthedocs? Seems like that would be the natural place rather than in the repo itself. I understand you also want to have rendered manifests so you can easily apply them, but I guess the primary motivation is the docs?

[olevski]

@ableuler I have one minor change request.

Everything else looks good.

Am I right in my understanding that whenever we merge or push something (i.e. new code) into the main branch this will trigger and submit a PR to update the manifests and crd docs?

What happens if there are no changes to the relevant files (i.e. templates and crd)? Do we still get a PR that has a blank diff?

[ableuler]

What happens if there are no changes to the relevant files (i.e. templates and crd)? Do we still get a PR that has a blank diff?

No, in this case the PR will be omitted entirely.

[ableuler]

I'm coming to this a bit late, but is there a reason not to have actual docs for amalthea on readthedocs? Seems like that would be the natural place rather than in the repo itself. I understand you also want to have rendered manifests so you can easily apply them, but I guess the primary motivation is the docs?

I originally came from the documentation aspect, but I think it's generally nice to publish the manifests too. I also want to have docs on read-the-docs and I actually hope that at some point when crdsdev/doc#156 is fixed that we can stop hosting the rendered CRD docs entirely and just point to https://doc.crds.dev/github.com/SwissDataScienceCenter/amalthea. But for the moment I think having the CRD docs inside the repo has a benefit.

[ableuler]

@rokroskar #92