1//Copyright 2015 Red Hat Inc. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6// http://www.apache.org/licenses/LICENSE-2.0
7//
8// Unless required by applicable law or agreed to in writing, software
9// distributed under the License is distributed on an "AS IS" BASIS,
10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11// See the License for the specific language governing permissions and
12// limitations under the License.
13
14package doc
15
16import (
17 "bytes"
18 "fmt"
19 "io"
20 "os"
21 "path/filepath"
22 "sort"
23 "strings"
24 "time"
25
26 "github.com/spf13/cobra"
27)
28
29func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
30 flags := cmd.NonInheritedFlags()
31 flags.SetOutput(buf)
32 if flags.HasAvailableFlags() {
33 buf.WriteString("### Options\n\n```\n")
34 flags.PrintDefaults()
35 buf.WriteString("```\n\n")
36 }
37
38 parentFlags := cmd.InheritedFlags()
39 parentFlags.SetOutput(buf)
40 if parentFlags.HasAvailableFlags() {
41 buf.WriteString("### Options inherited from parent commands\n\n```\n")
42 parentFlags.PrintDefaults()
43 buf.WriteString("```\n\n")
44 }
45 return nil
46}
47
48// GenMarkdown creates markdown output.
49func GenMarkdown(cmd *cobra.Command, w io.Writer) error {
50 return GenMarkdownCustom(cmd, w, func(s string) string { return s })
51}
52
53// GenMarkdownCustom creates custom markdown output.
54func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
55 cmd.InitDefaultHelpCmd()
56 cmd.InitDefaultHelpFlag()
57
58 buf := new(bytes.Buffer)
59 name := cmd.CommandPath()
60
61 short := cmd.Short
62 long := cmd.Long
63 if len(long) == 0 {
64 long = short
65 }
66
67 buf.WriteString("## " + name + "\n\n")
68 buf.WriteString(short + "\n\n")
69 buf.WriteString("### Synopsis\n\n")
70 buf.WriteString(long + "\n\n")
71
72 if cmd.Runnable() {
73 buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
74 }
75
76 if len(cmd.Example) > 0 {
77 buf.WriteString("### Examples\n\n")
78 buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))
79 }
80
81 if err := printOptions(buf, cmd, name); err != nil {
82 return err
83 }
84 if hasSeeAlso(cmd) {
85 buf.WriteString("### SEE ALSO\n\n")
86 if cmd.HasParent() {
87 parent := cmd.Parent()
88 pname := parent.CommandPath()
89 link := pname + ".md"
90 link = strings.Replace(link, " ", "_", -1)
91 buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short))
92 cmd.VisitParents(func(c *cobra.Command) {
93 if c.DisableAutoGenTag {
94 cmd.DisableAutoGenTag = c.DisableAutoGenTag
95 }
96 })
97 }
98
99 children := cmd.Commands()
100 sort.Sort(byName(children))
101
102 for _, child := range children {
103 if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
104 continue
105 }
106 cname := name + " " + child.Name()
107 link := cname + ".md"
108 link = strings.Replace(link, " ", "_", -1)
109 buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short))
110 }
111 buf.WriteString("\n")
112 }
113 if !cmd.DisableAutoGenTag {
114 buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
115 }
116 _, err := buf.WriteTo(w)
117 return err
118}
119
120// GenMarkdownTree will generate a markdown page for this command and all
121// descendants in the directory given. The header may be nil.
122// This function may not work correctly if your command names have `-` in them.
123// If you have `cmd` with two subcmds, `sub` and `sub-third`,
124// and `sub` has a subcommand called `third`, it is undefined which
125// help output will be in the file `cmd-sub-third.1`.
126func GenMarkdownTree(cmd *cobra.Command, dir string) error {
127 identity := func(s string) string { return s }
128 emptyStr := func(s string) string { return "" }
129 return GenMarkdownTreeCustom(cmd, dir, emptyStr, identity)
130}
131
132// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
133// with custom filePrepender and linkHandler.
134func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
135 for _, c := range cmd.Commands() {
136 if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
137 continue
138 }
139 if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
140 return err
141 }
142 }
143
144 basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
145 filename := filepath.Join(dir, basename)
146 f, err := os.Create(filename)
147 if err != nil {
148 return err
149 }
150 defer f.Close()
151
152 if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
153 return err
154 }
155 if err := GenMarkdownCustom(cmd, f, linkHandler); err != nil {
156 return err
157 }
158 return nil
159}