docs: add script to run kubectl explain on all crds

[Billy99]

Add a script that given the root CRD name, will run kubectl explain on all <Object> and sub-<Object> fields and pipe the output to a txt file that is checked in. Also add make explain to the Makefile to automate the running of the script. This serves two purposes:

1. Documents the CRDs in an easily readable format for users of the CRD.
2. Currently needs to be manually run, but shows how changes to the API effect the CRDs. This could be automated in the github workflow if the CRDs are loaded into a Kubernetes cluster in github actions.

[frobware]

The fundamental question is whether the slightly improved readability of kubectl explain output justifies having two copies of the same API documentation in the tree.

Other concerns: this doesn't actually catch regressions unless someone actively reads the output. Without a mechanism to fail the build when CRD structure changes unexpectedly or validate breaking changes, I worry this becomes write-only documentation.

[Billy99]

First, I'm fine if you don't want this, just letting you see what I had.

The fundamental question is whether the slightly improved readability of kubectl explain output justifies having two copies of the same API documentation in the tree.

The "improved readability" also shows spacing. If you look at fields that the description is in pulled in modules, like conditions, you can see the spacing is off and can really only be seen when output from kubectl explain. Example of condition output:

    Many .condition.type values are consistent across resources like Available,
    but because arbitrary conditions can be
    useful (see .node.status.conditions), the ability to deconflict is
    important.
    The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)

Not the end of the world, but would like our descriptions to be as clean as possible.

As far as two copies, I think you are referring to Kubernetes CRD API-Reference as the first copy? I think my version is easier to read and the docs are way outdated since they are only getting updated on releases (maybe should update them soon if a release isn't imminent).

Other concerns: this doesn't actually catch regressions unless someone actively reads the output. Without a mechanism to fail the build when CRD structure changes unexpectedly or validate breaking changes, I worry this becomes write-only documentation.

This isn't here yet, but I was thinking if we have the CRDs loaded in a cluster in any of CI, we could something like we do with the bundle, I just didn't dig to see if this was possible:

      - name: Verify generated bundle manifest
        if: ${{ matrix.arch.arch == 'amd64' }}
        run: |
          make bundle
          git diff --exit-code -I'^    createdAt: ' bundle

[frobware]

First, I'm fine if you don't want this, just letting you see what I had.

The fundamental question is whether the slightly improved readability of kubectl explain output justifies having two copies of the same API documentation in the tree.

The "improved readability" also shows spacing. If you look at fields that the description is in pulled in modules, like conditions, you can see the spacing is off and can really only be seen when output from kubectl explain. Example of condition output:

    Many .condition.type values are consistent across resources like Available,
    but because arbitrary conditions can be
    useful (see .node.status.conditions), the ability to deconflict is
    important.
    The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)

Not the end of the world, but would like our descriptions to be as clean as possible.

As far as two copies, I think you are referring to Kubernetes CRD API-Reference as the first copy? I think my version is easier to read and the docs are way outdated since they are only getting updated on releases (maybe should update them soon if a release isn't imminent).

ah. nope. :)

I wasn't aware of the developer-guide (link).

If you're working in the tree, then my "two copies" comment was the source in apis/..., and your txt version equivalents.