mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-02 14:42:56 +08:00
Paul GottschlingandhugoShaka
e272c842bd
* Auto-generate operator CRD docs We already pull JSON schema data from Teleport protobuf message definitions in order to generate CRD manifests. Extract a shared library from code within the existing protoc plugin for generating CRDs. This way, we can use the library to generate docs for our CRDs with a separate plugin, and don't need to complicate the interface for using the existing plugin. - Organize `integrations/crdgen` into `lib` and `cmd` directories, turning `lib` into a package. - Edit the `generateSchema` signature to include a function that formats a CRD into a document, injecting separate functions for formatting the CRD as YAML and as a docs page. - Add Makefile targets for building the docs plugin and generating CRD docs. To display the resulting reference pages in the docs, this change configures `docs/config.json` to generate the Reference section of the sidebar from the docs directory. This requires moving the Helm reference includes directory into `docs/pages/includes`. * Respond to hugoShaka feedback - Do not display the `status` field. - Indicate that enum fields can take an integer or a string. This is consistent with our comment conventions, which describe both the integer and the string values for each enum option. * Sort CRD reference page sections Also handle duplicate page sections by including the names of parent properties within section headings. * Fix crdgen Makefile targets - bring test data and hack out of `lib/` - fix broken debug builds - add crd-docs checks to the `crds-up-to-date` target - trigger proto lint on CRD and CRD doc changes - removed stale gitkeep in `docs/pages/includes/crd-docs/.gitkeep` - split crdgen formatting logic in another file for readability - update license header years on new files * fixup! Fix crdgen Makefile targets * lint files due to false positive 'generated' comment * fixup! lint files due to false positive 'generated' comment * Incorporate rosstimothy feedback Remove an unnecessary package. Also regenerate the CRD docs. * fix debug builds and gitignore * fixup! fix debug builds and gitignore * Respond to rosstimothy feedback Fix integrations/operator/crdgen/Makefile * Fix spelling * Fix flaky propertyTable test Compare the unsorted slice elements, since sorting takes place on the containing VersionSection. --------- Co-authored-by: hugoShaka <hugo.hervieux@goteleport.com>
64 lines
2.2 KiB
Go
64 lines
2.2 KiB
Go
//go:build debug
|
|
|
|
/*
|
|
* 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 crdgen
|
|
|
|
// This is an alternative main package that gets included when the `debug` tag
|
|
// is set. When built with this debug tag, the protoc plugin reads its input
|
|
// from a file instead of stdin. This allows to easily attach a debugger and
|
|
// inspect what is happening inside the plugin.
|
|
|
|
import (
|
|
"io"
|
|
"os"
|
|
|
|
"github.com/gogo/protobuf/proto"
|
|
"github.com/gogo/protobuf/protoc-gen-gogo/generator"
|
|
plugin "github.com/gogo/protobuf/protoc-gen-gogo/plugin"
|
|
"github.com/gravitational/trace"
|
|
)
|
|
|
|
// PluginInputPathEnvironment is the environment variable telling debug builds where the protoc request file is located.
|
|
const PluginInputPathEnvironment = "TELEPORT_PROTOC_READ_FILE"
|
|
|
|
// ReadRequestFromFile reads the protoc request from a file instead of stdin.
|
|
// This is used for debugging purposes (this allows to invoke the protoc plugin directly
|
|
// with a debugger attached).
|
|
func ReadRequestFromFile(inputPath string) (*plugin.CodeGeneratorRequest, error) {
|
|
g := generator.New()
|
|
inputFile, err := os.Open(inputPath)
|
|
if err != nil {
|
|
return nil, trace.Wrap(err)
|
|
}
|
|
data, err := io.ReadAll(inputFile)
|
|
if err != nil {
|
|
return nil, trace.WrapWithMessage(err, "failed to read input")
|
|
}
|
|
|
|
if err := proto.Unmarshal(data, g.Request); err != nil {
|
|
return nil, trace.WrapWithMessage(err, "failed to parse input proto")
|
|
}
|
|
|
|
if len(g.Request.FileToGenerate) == 0 {
|
|
return nil, trace.BadParameter("no files to generate")
|
|
}
|
|
return g.Request, nil
|
|
}
|