Add a resource reference generator

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.

build.assets/tooling/cmd/resource-ref-generator/README.md

@@ -0,0 +1,81 @@
+# Resource reference generator
+
+The resource reference generator is a Go program that produces a comprehensive
+reference guide for all dynamic Teleport resources and the fields they include.
+It uses the Teleport source as the basis for the guide. 
+
+## Usage
+
+```
+$ cd build.assets/tooling/cmd/resource-ref-generator
+$ go run . -config config.yaml
+```
+
+## How it works
+
+The resource reference generator works by:
+
+1. Identifying Go structs that correspond to dynamic Teleport resources.
+1. Identifying Go types that represent to the fields of each dynamic resource
+   struct.
+1. Retrieving reference information about dynamic resources and their fields
+   using a combination of Go comments and type information.
+
+### Editing source files
+
+The resource reference indicates which Go source files the reference generator
+used for each entry. The generator is only aware of Go source files, not
+protobuf message definitions.
+
+If a source file is based on a protobuf message definition, edit the message
+definition first, then run:
+
+```
+$ make grpc
+```
+
+After that, you can run the reference generator.
+
+## Configuration
+
+The generator uses a YAML configuration file with the following fields.
+
+### Main config
+
+- `required_field_types`: a list of type info mappings (see "Type info")
+  indicating type names of fields that must be present in a dynamic resource
+  before we include it in the reference. For example, if this is `Metadata` from
+  package `types`, a struct type must include a field with the a field of
+  `types.Metadata` before we add it to the reference.
+
+- `source` (string): the path to the root of a Go project directory.
+
+- `destination` (string): the directory path in which to place reference pages.
+
+- `excluded_resource_types`: a list of type info mappings (see "Type info")
+  indicating names of resources to exclude from the reference. 
+
+- `field_assignment_method`: the name of a method of a resource type that
+  assigns fields to the resource. Used to identify the kind and version of a
+  resource.
+
+### Type info
+
+- `package`: The path of a Go package
+- `name`: The name of a type within the package
+
+### Example
+
+```yaml
+required_field_types:
+  - name: Metadata
+    package: api/types
+  - name: ResourceHeader
+    package: api/types
+source: "api"
+destination: "docs/pages/includes/resource-reference.mdx"
+excluded_resource_types:
+  - package: "types"
+    name: "ResourceHeader"
+field_assignment_method: "setStaticFields"
+```

build.assets/tooling/cmd/resource-ref-generator/config.yaml

@@ -0,0 +1,20 @@
+required_field_types:
+  - package: "types"
+    name: "ResourceHeader"
+  - package: "types"
+    name: "Metadata"
+source: "../../../../api"
+destination: "../../../../docs/pages/reference/tctl-resources"
+excluded_resource_types:
+  - package: "types"
+    name: "ResourceHeader"
+  # PluginV1 is not intended to be user facing, as it configures hosted plugins.
+  - package: "types"
+    name: "PluginV1"
+  - package: "types"
+    name: "Namespace"
+  # This is an entire resource with a custom unmarshaler, so we should take care
+  # to determine how to document it.
+  - package: "types"
+    name: "MFADevice"
+field_assignment_method: "setStaticFields"

build.assets/tooling/cmd/resource-ref-generator/main.go

@@ -0,0 +1,91 @@
+// Teleport
+// Copyright (C) 2023  Gravitational, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/gravitational/teleport/build.assets/tooling/cmd/resource-ref-generator/reference"
+	"github.com/spf13/afero"
+	"gopkg.in/yaml.v2"
+)
+
+const configHelp string = `The path to a YAML configuration file with the following fields:
+
+## Main config
+
+required_field_types: a list of type info mappings (see "Type info") indicating
+type names of fields that must be present in a dynamic resource before we
+include it in the reference. For example, if this is "Metadata" from package
+"types", a struct type must include a field with the a field of "types.Metadata"
+before we add it to the reference.
+
+source (string): the path to the root of a Go project directory.
+
+destination (string): the path to a directory where the generator writes
+reference pages.
+
+excluded_resource_types: a list of type info mappings (see "Type info")
+indicating names of resources to exclude from the reference. 
+
+field_assignment_method: the name of a method of a resource type that assigns
+fields to the resource. Used to identify the kind and version of a resource.
+
+## Type info
+
+package: The path of a Go package
+name: The name of a type within the package
+
+## Example
+
+required_types:
+  - name: Metadata
+    package: api/types
+  - name: ResourceHeader
+    package: api/types
+source: "api"
+destination: "docs/pages/includes/resource-reference.mdx"
+excluded_resource_types:
+  - package: "types"
+    name: "ResourceHeader"
+field_assignment_method: "setStaticFields"
+`
+
+func main() {
+	conf := flag.String("config", "./conf.yaml", configHelp)
+	flag.Parse()
+
+	conffile, err := os.Open(*conf)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Could not open the configuration file %v: %v\n", *conf, err)
+		os.Exit(1)
+	}
+	genconf := reference.GeneratorConfig{}
+	if err := yaml.NewDecoder(conffile).Decode(&genconf); err != nil {
+		fmt.Fprintf(os.Stderr, "Invalid configuration file: %v\n", err)
+		os.Exit(1)
+	}
+
+	osFS := afero.NewOsFs()
+	err = reference.Generate(osFS, osFS, genconf)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Could not generate the resource reference: %v\n", err)
+		os.Exit(1)
+	}
+}