mirror of
https://github.com/spf13/cobra
synced 2024-11-04 21:07:19 +00:00
Added support for yaml ouptut in docs gen (#380)
Signed-off-by: French Ben <frenchben@docker.com>
This commit is contained in:
parent
c29ece4386
commit
35136c09d8
5 changed files with 373 additions and 4 deletions
|
@ -32,15 +32,15 @@ import (
|
||||||
"io/ioutil"
|
"io/ioutil"
|
||||||
"os"
|
"os"
|
||||||
|
|
||||||
kubectlcmd "k8s.io/kubernetes/pkg/kubectl/cmd"
|
"k8s.io/kubernetes/pkg/kubectl/cmd"
|
||||||
cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
|
cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
|
||||||
|
|
||||||
"github.com/spf13/cobra/doc"
|
"github.com/spf13/cobra/doc"
|
||||||
)
|
)
|
||||||
|
|
||||||
func main() {
|
func main() {
|
||||||
cmd := kubectlcmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
|
kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
|
||||||
doc.GenMarkdownTree(cmd, "./")
|
doc.GenMarkdownTree(kubectl, "./")
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
15
doc/util.go
15
doc/util.go
|
@ -13,7 +13,11 @@
|
||||||
|
|
||||||
package doc
|
package doc
|
||||||
|
|
||||||
import "github.com/spf13/cobra"
|
import (
|
||||||
|
"strings"
|
||||||
|
|
||||||
|
"github.com/spf13/cobra"
|
||||||
|
)
|
||||||
|
|
||||||
// Test to see if we have a reason to print See Also information in docs
|
// Test to see if we have a reason to print See Also information in docs
|
||||||
// Basically this is a test for a parent commend or a subcommand which is
|
// Basically this is a test for a parent commend or a subcommand which is
|
||||||
|
@ -31,6 +35,15 @@ func hasSeeAlso(cmd *cobra.Command) bool {
|
||||||
return false
|
return false
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Temporary workaround for yaml lib generating incorrect yaml with long strings
|
||||||
|
// that do not contain \n.
|
||||||
|
func forceMultiLine(s string) string {
|
||||||
|
if len(s) > 60 && !strings.Contains(s, "\n") {
|
||||||
|
s = s + "\n"
|
||||||
|
}
|
||||||
|
return s
|
||||||
|
}
|
||||||
|
|
||||||
type byName []*cobra.Command
|
type byName []*cobra.Command
|
||||||
|
|
||||||
func (s byName) Len() int { return len(s) }
|
func (s byName) Len() int { return len(s) }
|
||||||
|
|
165
doc/yaml_docs.go
Normal file
165
doc/yaml_docs.go
Normal file
|
@ -0,0 +1,165 @@
|
||||||
|
// Copyright 2016 French Ben. All rights reserved.
|
||||||
|
//
|
||||||
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
// you may not use this file except in compliance with the License.
|
||||||
|
// You may obtain a copy of the License at
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
//
|
||||||
|
// Unless required by applicable law or agreed to in writing, software
|
||||||
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
// See the License for the specific language governing permissions and
|
||||||
|
// limitations under the License.
|
||||||
|
|
||||||
|
package doc
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"sort"
|
||||||
|
"strings"
|
||||||
|
|
||||||
|
"github.com/spf13/cobra"
|
||||||
|
"github.com/spf13/pflag"
|
||||||
|
"gopkg.in/yaml.v2"
|
||||||
|
)
|
||||||
|
|
||||||
|
type cmdOption struct {
|
||||||
|
Name string
|
||||||
|
Shorthand string `yaml:",omitempty"`
|
||||||
|
DefaultValue string `yaml:"default_value,omitempty"`
|
||||||
|
Usage string `yaml:",omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type cmdDoc struct {
|
||||||
|
Name string
|
||||||
|
Synopsis string `yaml:",omitempty"`
|
||||||
|
Description string `yaml:",omitempty"`
|
||||||
|
Options []cmdOption `yaml:",omitempty"`
|
||||||
|
InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
|
||||||
|
Example string `yaml:",omitempty"`
|
||||||
|
SeeAlso []string `yaml:"see_also,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// GenYamlTree creates yaml structured ref files for this command and all descendants
|
||||||
|
// in the directory given. This function may not work
|
||||||
|
// correctly if your command names have - in them. If you have `cmd` with two
|
||||||
|
// subcmds, `sub` and `sub-third`. And `sub` has a subcommand called `third`
|
||||||
|
// it is undefined which help output will be in the file `cmd-sub-third.1`.
|
||||||
|
func GenYamlTree(cmd *cobra.Command, dir string) error {
|
||||||
|
identity := func(s string) string { return s }
|
||||||
|
emptyStr := func(s string) string { return "" }
|
||||||
|
return GenYamlTreeCustom(cmd, dir, emptyStr, identity)
|
||||||
|
}
|
||||||
|
|
||||||
|
// GenYamlTreeCustom creates yaml structured ref files
|
||||||
|
func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
|
||||||
|
for _, c := range cmd.Commands() {
|
||||||
|
if !c.IsAvailableCommand() || c.IsHelpCommand() {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
if err := GenYamlTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
|
||||||
|
filename := filepath.Join(dir, basename)
|
||||||
|
f, err := os.Create(filename)
|
||||||
|
if err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
defer f.Close()
|
||||||
|
|
||||||
|
if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
if err := GenYamlCustom(cmd, f, linkHandler); err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// GenYaml creates yaml output
|
||||||
|
func GenYaml(cmd *cobra.Command, w io.Writer) error {
|
||||||
|
return GenYamlCustom(cmd, w, func(s string) string { return s })
|
||||||
|
}
|
||||||
|
|
||||||
|
// GenYamlCustom creates custom yaml output
|
||||||
|
func GenYamlCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
|
||||||
|
yamlDoc := cmdDoc{}
|
||||||
|
yamlDoc.Name = cmd.CommandPath()
|
||||||
|
|
||||||
|
yamlDoc.Synopsis = forceMultiLine(cmd.Short)
|
||||||
|
yamlDoc.Description = forceMultiLine(cmd.Long)
|
||||||
|
|
||||||
|
if len(cmd.Example) > 0 {
|
||||||
|
yamlDoc.Example = cmd.Example
|
||||||
|
}
|
||||||
|
|
||||||
|
flags := cmd.NonInheritedFlags()
|
||||||
|
if flags.HasFlags() {
|
||||||
|
yamlDoc.Options = genFlagResult(flags)
|
||||||
|
}
|
||||||
|
flags = cmd.InheritedFlags()
|
||||||
|
if flags.HasFlags() {
|
||||||
|
yamlDoc.InheritedOptions = genFlagResult(flags)
|
||||||
|
}
|
||||||
|
|
||||||
|
if hasSeeAlso(cmd) {
|
||||||
|
result := []string{}
|
||||||
|
if cmd.HasParent() {
|
||||||
|
parent := cmd.Parent()
|
||||||
|
result = append(result, parent.CommandPath()+" - "+parent.Short)
|
||||||
|
}
|
||||||
|
children := cmd.Commands()
|
||||||
|
sort.Sort(byName(children))
|
||||||
|
for _, child := range children {
|
||||||
|
if !child.IsAvailableCommand() || child.IsHelpCommand() {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
result = append(result, child.Name()+" - "+child.Short)
|
||||||
|
}
|
||||||
|
yamlDoc.SeeAlso = result
|
||||||
|
}
|
||||||
|
|
||||||
|
final, err := yaml.Marshal(&yamlDoc)
|
||||||
|
if err != nil {
|
||||||
|
fmt.Println(err)
|
||||||
|
os.Exit(1)
|
||||||
|
}
|
||||||
|
if _, err := fmt.Fprintf(w, string(final)); err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func genFlagResult(flags *pflag.FlagSet) []cmdOption {
|
||||||
|
var result []cmdOption
|
||||||
|
|
||||||
|
flags.VisitAll(func(flag *pflag.Flag) {
|
||||||
|
// Todo, when we mark a shorthand is deprecated, but specify an empty message.
|
||||||
|
// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
|
||||||
|
// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
|
||||||
|
if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
|
||||||
|
opt := cmdOption{
|
||||||
|
flag.Name,
|
||||||
|
flag.Shorthand,
|
||||||
|
flag.DefValue,
|
||||||
|
forceMultiLine(flag.Usage),
|
||||||
|
}
|
||||||
|
result = append(result, opt)
|
||||||
|
} else {
|
||||||
|
opt := cmdOption{
|
||||||
|
Name: flag.Name,
|
||||||
|
DefaultValue: forceMultiLine(flag.DefValue),
|
||||||
|
Usage: forceMultiLine(flag.Usage),
|
||||||
|
}
|
||||||
|
result = append(result, opt)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
return result
|
||||||
|
}
|
103
doc/yaml_docs.md
Normal file
103
doc/yaml_docs.md
Normal file
|
@ -0,0 +1,103 @@
|
||||||
|
# Generating Yaml Docs For Your Own cobra.Command
|
||||||
|
|
||||||
|
Generating yaml files from a cobra command is incredibly easy. An example is as follows:
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"github.com/spf13/cobra"
|
||||||
|
"github.com/spf13/cobra/doc"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
cmd := &cobra.Command{
|
||||||
|
Use: "test",
|
||||||
|
Short: "my test program",
|
||||||
|
}
|
||||||
|
doc.GenYamlTree(cmd, "/tmp")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
That will get you a Yaml document `/tmp/test.yaml`
|
||||||
|
|
||||||
|
## Generate yaml docs for the entire command tree
|
||||||
|
|
||||||
|
This program can actually generate docs for the kubectl command in the kubernetes project
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"io/ioutil"
|
||||||
|
"os"
|
||||||
|
|
||||||
|
"k8s.io/kubernetes/pkg/kubectl/cmd"
|
||||||
|
cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
|
||||||
|
|
||||||
|
"github.com/spf13/cobra/doc"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
|
||||||
|
doc.GenYamlTree(kubectl, "./")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
||||||
|
|
||||||
|
## Generate yaml docs for a single command
|
||||||
|
|
||||||
|
You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenYaml` instead of `GenYamlTree`
|
||||||
|
|
||||||
|
```go
|
||||||
|
out := new(bytes.Buffer)
|
||||||
|
doc.GenYaml(cmd, out)
|
||||||
|
```
|
||||||
|
|
||||||
|
This will write the yaml doc for ONLY "cmd" into the out, buffer.
|
||||||
|
|
||||||
|
## Customize the output
|
||||||
|
|
||||||
|
Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output:
|
||||||
|
|
||||||
|
```go
|
||||||
|
func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
|
||||||
|
//...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```go
|
||||||
|
func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
|
||||||
|
//...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `filePrepender` will prepend the return value given the full filepath to the rendered Yaml file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
|
||||||
|
|
||||||
|
```go
|
||||||
|
const fmTemplate = `---
|
||||||
|
date: %s
|
||||||
|
title: "%s"
|
||||||
|
slug: %s
|
||||||
|
url: %s
|
||||||
|
---
|
||||||
|
`
|
||||||
|
|
||||||
|
filePrepender := func(filename string) string {
|
||||||
|
now := time.Now().Format(time.RFC3339)
|
||||||
|
name := filepath.Base(filename)
|
||||||
|
base := strings.TrimSuffix(name, path.Ext(name))
|
||||||
|
url := "/commands/" + strings.ToLower(base) + "/"
|
||||||
|
return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
|
||||||
|
|
||||||
|
```go
|
||||||
|
linkHandler := func(name string) string {
|
||||||
|
base := strings.TrimSuffix(name, path.Ext(name))
|
||||||
|
return "/commands/" + strings.ToLower(base) + "/"
|
||||||
|
}
|
||||||
|
```
|
88
doc/yaml_docs_test.go
Normal file
88
doc/yaml_docs_test.go
Normal file
|
@ -0,0 +1,88 @@
|
||||||
|
package doc
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"fmt"
|
||||||
|
"os"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
var _ = fmt.Println
|
||||||
|
var _ = os.Stderr
|
||||||
|
|
||||||
|
func TestGenYamlDoc(t *testing.T) {
|
||||||
|
c := initializeWithRootCmd()
|
||||||
|
// Need two commands to run the command alphabetical sort
|
||||||
|
cmdEcho.AddCommand(cmdTimes, cmdEchoSub, cmdDeprecated)
|
||||||
|
c.AddCommand(cmdPrint, cmdEcho)
|
||||||
|
cmdRootWithRun.PersistentFlags().StringVarP(&flags2a, "rootflag", "r", "two", strtwoParentHelp)
|
||||||
|
|
||||||
|
out := new(bytes.Buffer)
|
||||||
|
|
||||||
|
// We generate on s subcommand so we have both subcommands and parents
|
||||||
|
if err := GenYaml(cmdEcho, out); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
found := out.String()
|
||||||
|
|
||||||
|
// Our description
|
||||||
|
expected := cmdEcho.Long
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Better have our example
|
||||||
|
expected = cmdEcho.Example
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
// A local flag
|
||||||
|
expected = "boolone"
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
// persistent flag on parent
|
||||||
|
expected = "rootflag"
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
// We better output info about our parent
|
||||||
|
expected = cmdRootWithRun.Short
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
// And about subcommands
|
||||||
|
expected = cmdEchoSub.Short
|
||||||
|
if !strings.Contains(found, expected) {
|
||||||
|
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
|
||||||
|
}
|
||||||
|
|
||||||
|
unexpected := cmdDeprecated.Short
|
||||||
|
if strings.Contains(found, unexpected) {
|
||||||
|
t.Errorf("Unexpected response.\nFound: %v\nBut should not have!!\n", unexpected)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestGenYamlNoTag(t *testing.T) {
|
||||||
|
c := initializeWithRootCmd()
|
||||||
|
// Need two commands to run the command alphabetical sort
|
||||||
|
cmdEcho.AddCommand(cmdTimes, cmdEchoSub, cmdDeprecated)
|
||||||
|
c.AddCommand(cmdPrint, cmdEcho)
|
||||||
|
c.DisableAutoGenTag = true
|
||||||
|
cmdRootWithRun.PersistentFlags().StringVarP(&flags2a, "rootflag", "r", "two", strtwoParentHelp)
|
||||||
|
out := new(bytes.Buffer)
|
||||||
|
|
||||||
|
if err := GenYaml(c, out); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
found := out.String()
|
||||||
|
|
||||||
|
unexpected := "Auto generated"
|
||||||
|
checkStringOmits(t, found, unexpected)
|
||||||
|
|
||||||
|
}
|
Loading…
Reference in a new issue