Documentation improvements

[seaneagan]

This attempts to work towards the extend documentation around managing Helm releases task mentioned in fluxcd/flux2#238:

The thought here is to have a leveled documentation, increasing detail in each level, and avoiding too much duplication between levels:

1. https://toolkit.fluxcd.io/guides/helmreleases
2. https://toolkit.fluxcd.io/components/helm/helmreleases/
3. https://toolkit.fluxcd.io/components/helm/api/

This:

• copies some of the content about HelmRelease CRD options from 1. to 2. with the idea being to remove or reduce it from 1. and replace with a more prominent link to 2. (as a follow up in the toolkit repo).
• adds more documentation to 2.
• removes some of the copy/pasted golang documentation from 2. since it already exists in 3. The status condition types / reasons are kept (though moved under the status section) since those are not currently included in 3. This could be potentially be resolved in the future by Emit documentation for typed constants ahmetb/gen-crd-api-reference-docs#21

[hiddeco]

Thanks for putting time into this 🥝

I have to think for a bit about removing the structures from the spec docs, but do have some comments in the meantime.

[hiddeco]

I have to think for a bit about removing the structures from the spec docs, but do have some comments in the meantime.

I discussed this a bit with @stefanprodan, and we both think the in-documentation code blocks should stay. Reason for this is that once we get out of the "rapid development cycle", new proposals should be made against the spec, and this becomes hard without them being available. We are currently working on more governance (including documentation) for the Flux project, and I will make sure this process will be documented somewhere (cc: @scottrigby).

I also think this means that the documentation within the spec that is added in this PR should be rewritten to something that describes desired application behaviour, instead of being explanatory to a user. But this can be taken care of as a follow up action, including moving bits and pieces to the HelmRelease guide (which targets users).

I took the liberty to rebase the PR and undo the code removals from the spec so this can be merged in the meantime, as we are trying to make new controller releases today and would like to see this included.

[stefanprodan]

LGTM

GG @seaneagan and @hiddeco