Rewrite spec documentation in more user-friendly format

[hiddeco]

The source-controller v1beta2 API comes with a new format for the spec documentation, which is more in-line with the documentation from e.g. Kubernetes workload resources itself and does not include (for the end-user confusing) Go code.

It would be good to apply this structure to the spec documentation for the other controllers as well.

New format outline

# <API type>

## Example

Contains an example of a minimal YAML for the type, and explains (in steps) what happens when the controller reconciles this type.

## Writing a <API type> spec

Contains documentation for all the fields, and the impact they have when specified.

## Working with <API type>

Contains practical examples about working with the type, e.g. triggering on-demand reconciles, waiting for a `Ready` state, etc.

## <API type> Status

Explains in detail the Conditions and other Status fields the object may have.

(For a detailed example, see e.g. https://github.com/fluxcd/source-controller/blob/main/docs/spec/v1beta2/gitrepositories.md)

To-do

• [x] source-controller: https://github.com/fluxcd/source-controller/pull/599
• [ ] kustomize-controller
• [ ] helm-controller
• [ ] image-automation-controller
• [ ] image-reflector-controller