From f6646eb2b79a4fcf2687a4e0bac1a6b321fad517 Mon Sep 17 00:00:00 2001 From: Andrew Keesler Date: Mon, 22 Mar 2021 12:40:29 -0400 Subject: [PATCH] cmd/pinniped: add generate-markdown-help for generating CLI doc This command is hidden. We want to use this to generate our CLI reference docs upon release. Signed-off-by: Andrew Keesler --- cmd/pinniped/cmd/generate_markdown_help.go | 114 +++++++++++++++++++++ go.sum | 5 + 2 files changed, 119 insertions(+) create mode 100644 cmd/pinniped/cmd/generate_markdown_help.go diff --git a/cmd/pinniped/cmd/generate_markdown_help.go b/cmd/pinniped/cmd/generate_markdown_help.go new file mode 100644 index 00000000..92cc66d8 --- /dev/null +++ b/cmd/pinniped/cmd/generate_markdown_help.go @@ -0,0 +1,114 @@ +// Copyright 2020-2021 the Pinniped contributors. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +package cmd + +import ( + "bufio" + "bytes" + "fmt" + "io" + "strings" + + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +//nolint: gochecknoinits +func init() { + rootCmd.AddCommand(generateMarkdownHelpCommand()) +} + +func generateMarkdownHelpCommand() *cobra.Command { + return &cobra.Command{ + Args: cobra.NoArgs, + Use: "generate-markdown-help", + Short: "Generate markdown help for the current set of non-hidden CLI commands", + SilenceUsage: true, + Hidden: true, + RunE: runGenerateMarkdownHelp, + } +} + +func runGenerateMarkdownHelp(cmd *cobra.Command, _ []string) error { + var generated bytes.Buffer + if err := generate(&generated); err != nil { + return err + } + if err := write(cmd.OutOrStdout(), &generated, "###### Auto generated by spf13/cobra"); err != nil { + return err + } + return nil +} + +func generate(w io.Writer) error { + if err := generateHeader(w); err != nil { + return err + } + if err := generateCommand(w, rootCmd); err != nil { + return err + } + return nil +} + +func generateHeader(w io.Writer) error { + _, err := fmt.Fprintf(w, `--- +title: Command-Line Options Reference +description: Reference for the `+"`pinniped`"+` command-line tool +cascade: + layout: docs +menu: + docs: + name: Command-Line Options + weight: 30 + parent: reference +--- + +`) + return err +} + +func generateCommand(w io.Writer, command *cobra.Command) error { + for _, command := range command.Commands() { + // if this node is hidden, don't traverse it or its descendents + if command.Hidden { + continue + } + + // generate children + if err := generateCommand(w, command); err != nil { + return err + } + + // generate self, but only if we are a command that people would run to do something interesting + if command.Run != nil || command.RunE != nil { + if err := doc.GenMarkdownCustom(command, w, func(_ string) string { return "" }); err != nil { + return err + } + } + } + + return nil +} + +func write(w io.Writer, r io.Reader, unwantedPrefixes ...string) error { + s := bufio.NewScanner(r) + for s.Scan() { + line := s.Text() + if !containsPrefix(line, unwantedPrefixes) { + if _, err := fmt.Fprintln(w, line); err != nil { + return err + } + } + } + return s.Err() +} + +func containsPrefix(s string, prefixes []string) bool { + for _, prefix := range prefixes { + if strings.HasPrefix(s, prefix) { + return true + } + } + return false +} diff --git a/go.sum b/go.sum index d8a68fbe..f7564f36 100644 --- a/go.sum +++ b/go.sum @@ -141,7 +141,9 @@ github.com/coreos/go-systemd v0.0.0-20190719114852-fd7a80b32e1f/go.mod h1:F5haX7 github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA= github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f h1:lBNOc5arjvs8E5mO2tbpBpLoyyu8B6e44T7hJy6potg= github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA= +github.com/cpuguy83/go-md2man v1.0.10 h1:BSKMNlYxDvnunlTymqtgONjNnaRV1sTpcovwwjF22jk= github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE= +github.com/cpuguy83/go-md2man/v2 v2.0.0 h1:EoUDS0afbrsXAZ9YQ9jdu/mZ2sXgT1/2yyNng4PGlyM= github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= @@ -902,7 +904,9 @@ github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ= github.com/rs/zerolog v1.13.0/go.mod h1:YbFCdg8HfsridGWAh22vktObvhZbQsZXe4/zB0OKkWU= github.com/rs/zerolog v1.15.0/go.mod h1:xYTKnLHcpfU2225ny5qZjxnj9NvkumZYjJHlAThCjNc= github.com/rubenv/sql-migrate v0.0.0-20190212093014-1007f53448d7/go.mod h1:WS0rl9eEliYI8DPnr3TOwz4439pay+qNgzJoVya/DmY= +github.com/russross/blackfriday v1.5.2 h1:HyvC0ARfnZBqnXwABFeSZHpKvJHJJfPz81GNueLj0oo= github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g= +github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q= github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts= github.com/santhosh-tekuri/jsonschema v1.2.4/go.mod h1:TEAUOeZSmIxTTuHatJzrvARHiuO9LYd+cIxzgEHCQI4= @@ -930,6 +934,7 @@ github.com/shurcooL/highlight_diff v0.0.0-20170515013008-09bb4053de1b/go.mod h1: github.com/shurcooL/highlight_go v0.0.0-20170515013102-78fb10f4a5f8/go.mod h1:UDKB5a1T23gOMUJrI+uSuH0VRDStOiUVSjBTRDVBVag= github.com/shurcooL/octicon v0.0.0-20180602230221-c42b0e3b24d9/go.mod h1:eWdoE5JD4R5UVWDucdOPg1g2fqQRq78IQa9zlOV1vpQ= github.com/shurcooL/sanitized_anchor_name v0.0.0-20170918181015-86672fcb3f95/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc= +github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo= github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc= github.com/sirupsen/logrus v1.0.4-0.20170822132746-89742aefa4b2/go.mod h1:pMByvHTf9Beacp5x1UXfOR9xyW/9antXMhjMPG0dEzc= github.com/sirupsen/logrus v1.0.6/go.mod h1:pMByvHTf9Beacp5x1UXfOR9xyW/9antXMhjMPG0dEzc=