Add a resource reference generator

[ptgott]

Closes #16948
Closes #9949
Closes #39564

Implements RFD 130.

See the included README for information about how the generator works.

This implementation breaks from RFD 130 in the following ways:

• The reference includes separate pages for dynamic resources in order to make it easier to read.
• The generator specifies the kind and version of each dynamic resource. To do this, the generator looks up a method called for each resource type to assign the type's version and kind.
• The generator uses a YAML configuration file. This is because the config ended up including more fields than specified in the RFD, so separating the config from the source made sense to give users less noise to deal with.
• In the example YAML blocks and type table values, leave types empty if we can't process them.

Edit the RFD:

• Be less specific about the output template so this isn't wedded to implementation details.
• Remove the description of example YAML delimiters. These are no longer viable, as we maintain several documentation generators that extract comments from the source.

[public-teleport-github-review-bot]

@ptgott - this PR will require admin approval to merge due to its size. Consider breaking it up into a series smaller changes.

[github-actions]

🤖 Vercel preview here: https://docs-771hg03b4-goteleport.vercel.app/docs

[ptgott]

Reviewer note: this PR doesn't include generated docs, since that would make the diff even larger than it is now.

[github-actions]

Amplify deployment status

Branch	Commit	Job ID	Status	Preview	Updated (UTC)
paul.gottschling/2024-12-9949-resources	206fa52	21	✅SUCCEED	paul-gottschling-2024-12-9949-resources	2025-02-20 17:03:27

[zmb3]

Seems reasonable, I'll have to test it out soon!

[strideynet]

First pass looks generally good - glad to see this being worked on!

I think my major concern is there may be parts of this generator that expect/rely on the resource being an old-style resource prior to RFD153 that is generated by GoGo Protobuf. I'd recommend possibly including a new RFD153-compliant resource in your testdata to ensure it'll work with the newest stuff (e.g the Bot resource is one of these)

[ptgott]

First pass looks generally good - glad to see this being worked on!

I think my major concern is there may be parts of this generator that expect/rely on the resource being an old-style resource prior to RFD153 that is generated by GoGo Protobuf. I'd recommend possibly including a new RFD153-compliant resource in your testdata to ensure it'll work with the newest stuff (e.g the Bot resource is one of these)

Thanks for the feedback! I've pushed a change in e8b2609 to support RFD153-compliant resources. The biggest issue I had here was that there doesn't seem to be a consistent way to assign the kind and version fields for these resources, so we may need to figure out a way to do this manually in a separate change.

[zmb3]

Consider adding a make target to the root makefile.

[ptgott]

So far, the root Makefile has targets for checking that auto-generated docs are up to date (here), but not for generating the docs. I could follow this convention and put the target in build.assets/Makefile, though a comment in the file says this is for producing official Teleport releases. At the same time, a root make target for running the docs generators would be nice, since they're spread throughout the source.

Come to think of it, is build.assets/tooling/cmd the best place for this project? Would it make sense to place it in docs?

[zmb3]

Should we move this line to the top of the file and make it a bit louder so people don't unintentionally try to edit this file?

I'm not sure if gopls operates on .tmpl files, but if it does there's a standard "code generated" comment that will actually tell editors to warn users who try to edit generated files.

[ptgott]

I've moved the line to the top of each generated file, but wasn't able to find details about standard "code generated" comments that cause editor warnings. I've seen "DO NOT EDIT" used a lot, so I've added that text.