vendor/github.com/spf13/cobra/doc/md_docs.go

   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
  14 package doc
  15
  16 import (
  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
  29 func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
  30         flags := cmd.NonInheritedFlags()
  31         flags.SetOutput(buf)
  32         if flags.HasFlags() {
  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.HasFlags() {
  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.
  49 func 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.
  54 func 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("\n" + 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")
  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`.
 126 func 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.
 134 func 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 }