Add a resource reference generator #50515
Conversation
github-actions
bot
requested review from
EdwardDowling,
mmcallister,
r0mant,
xinding33 and
zmb3
|
@ptgott - this PR will require admin approval to merge due to its size. Consider breaking it up into a series smaller changes. |
|
🤖 Vercel preview here: https://docs-771hg03b4-goteleport.vercel.app/docs |
|
Reviewer note: this PR doesn't include generated docs, since that would make the diff even larger than it is now. |
Closes #16948 Closes #9949 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.
ptgott
force-pushed
the
paul.gottschling/2024-12-9949-resources
branch
from
145bf35 to
04d814b
Compare
|
Amplify deployment status
|
|
|
||
| // Intended to be executed with a ReferenceContent. | ||
| // Ampersands are replaced with backticks. | ||
| var referenceTemplate string = strings.ReplaceAll(`--- |
There was a problem hiding this comment.
Alternatively, we could avoid the awkward strings.ReplaceAll and &&& by putting the contents of this template in a file and pulling it into a string via //go:embed.
| "golang.org/x/tools/go/ast/astutil" | ||
| ) | ||
|
|
||
| // Package is used to look up a Go declaration in a map of declaration names to |
There was a problem hiding this comment.
| // Package is used to look up a Go declaration in a map of declaration names to | |
| // PackageInfo is used to look up a Go declaration in a map of declaration names to |
| ` | ||
|
|
||
| func main() { | ||
| conf := flag.String("config", "./conf.yaml", configHelp) |
There was a problem hiding this comment.
| conf := flag.String("config", "./conf.yaml", configHelp) | |
| conf := flag.String("config", "conf.yaml", configHelp) |
| pc.Resource.Version = verName | ||
|
|
||
| filename := strings.ReplaceAll(strings.ToLower(pc.Resource.SectionName), " ", "-") | ||
| doc, err := destFS.Create(path.Join(conf.DestinationDirectory, filename+".mdx")) |
There was a problem hiding this comment.
Should this be filepath.Join, or does the afero FS take care of that for you?
| errs.messages = append(errs.messages, err) | ||
| } | ||
|
|
||
| if err := template.Must(template.New("Main reference").Parse(referenceTemplate)).Execute(doc, pc); err != nil { |
There was a problem hiding this comment.
I would parse the template once outside of the loop (potentially even in an init func) and then reuse it here. Otherwise we're wasting time re-parsing the same template multiple times.
| @@ -69,6 +69,8 @@ require ( | |||
| sigs.k8s.io/yaml v1.4.0 // indirect | |||
| ) | |||
|
|
|||
| require github.com/spf13/afero v1.9.2 | |||
There was a problem hiding this comment.
Move this up into the main require block. (The go tool doesn't do this for you sometimes, but you can just move the line manually)
Closes #16948
Closes #9949
Implements RFD 130.
See the included README for information about how the generator works.
This implementation breaks from RFD 130 in the following ways:
Edit the RFD: