spf13--cobra/doc/man_docs.go

219 lines
5.9 KiB
Go
Raw Normal View History

2015-08-18 22:33:41 +00:00
// Copyright 2015 Red Hat Inc. 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
2015-08-18 22:33:41 +00:00
import (
"bytes"
"fmt"
"io"
2015-08-18 22:33:41 +00:00
"os"
"path/filepath"
2015-08-18 22:33:41 +00:00
"sort"
"strings"
"time"
mangen "github.com/cpuguy83/go-md2man/md2man"
"github.com/spf13/cobra"
2015-08-18 22:33:41 +00:00
"github.com/spf13/pflag"
)
2016-06-07 10:50:48 +00:00
// GenManTree will generate a man page for this command and all descendants
// in the directory given. The header may be nil. 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 GenManTree(cmd *cobra.Command, header *GenManHeader, dir string) error {
if header == nil {
header = &GenManHeader{}
}
2015-08-18 22:33:41 +00:00
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsHelpCommand() {
2015-08-18 22:33:41 +00:00
continue
}
if err := GenManTree(c, header, dir); err != nil {
return err
}
2015-08-18 22:33:41 +00:00
}
needToResetTitle := header.Title == ""
basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".1"
filename := filepath.Join(dir, basename)
f, err := os.Create(filename)
2015-08-18 22:33:41 +00:00
if err != nil {
return err
2015-08-18 22:33:41 +00:00
}
defer f.Close()
if err := GenMan(cmd, header, f); err != nil {
return err
}
if needToResetTitle {
header.Title = ""
2015-08-18 22:33:41 +00:00
}
return nil
2015-08-18 22:33:41 +00:00
}
// GenManHeader is a lot like the .TH header at the start of man pages. These
// include the title, section, date, source, and manual. We will use the
// current time if Date if unset and will use "Auto generated by spf13/cobra"
// if the Source is unset.
type GenManHeader struct {
Title string
Section string
Date *time.Time
date string
Source string
Manual string
2015-08-18 22:33:41 +00:00
}
// GenMan will generate a man page for the given command and write it to
// w. The header argument may be nil, however obviously w may not.
func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error {
if header == nil {
header = &GenManHeader{}
}
b := genMan(cmd, header)
final := mangen.Render(b)
_, err := w.Write(final)
return err
2015-08-18 22:33:41 +00:00
}
func fillHeader(header *GenManHeader, name string) {
if header.Title == "" {
header.Title = strings.ToUpper(strings.Replace(name, " ", "\\-", -1))
}
if header.Section == "" {
header.Section = "1"
}
if header.Date == nil {
now := time.Now()
header.Date = &now
}
header.date = (*header.Date).Format("Jan 2006")
if header.Source == "" {
header.Source = "Auto generated by spf13/cobra"
}
}
func manPreamble(out io.Writer, header *GenManHeader, name, short, long string) {
dashName := strings.Replace(name, " ", "-", -1)
fmt.Fprintf(out, `%% %s(%s)%s
%% %s
%% %s
2015-08-18 22:33:41 +00:00
# NAME
`, header.Title, header.Section, header.date, header.Source, header.Manual)
fmt.Fprintf(out, "%s \\- %s\n\n", dashName, short)
2015-08-18 22:33:41 +00:00
fmt.Fprintf(out, "# SYNOPSIS\n")
fmt.Fprintf(out, "**%s** [OPTIONS]\n\n", name)
fmt.Fprintf(out, "# DESCRIPTION\n")
fmt.Fprintf(out, "%s\n\n", long)
}
func manPrintFlags(out io.Writer, flags *pflag.FlagSet) {
2015-08-18 22:33:41 +00:00
flags.VisitAll(func(flag *pflag.Flag) {
if len(flag.Deprecated) > 0 || flag.Hidden {
2015-08-18 22:33:41 +00:00
return
}
format := ""
if len(flag.Shorthand) > 0 {
format = "**-%s**, **--%s**"
} else {
format = "%s**--%s**"
}
if len(flag.NoOptDefVal) > 0 {
format = format + "["
}
if flag.Value.Type() == "string" {
// put quotes on the value
format = format + "=%q"
} else {
format = format + "=%s"
}
if len(flag.NoOptDefVal) > 0 {
format = format + "]"
}
format = format + "\n\t%s\n\n"
fmt.Fprintf(out, format, flag.Shorthand, flag.Name, flag.DefValue, flag.Usage)
})
}
func manPrintOptions(out io.Writer, command *cobra.Command) {
2015-08-18 22:33:41 +00:00
flags := command.NonInheritedFlags()
if flags.HasFlags() {
fmt.Fprintf(out, "# OPTIONS\n")
manPrintFlags(out, flags)
fmt.Fprintf(out, "\n")
}
flags = command.InheritedFlags()
if flags.HasFlags() {
fmt.Fprintf(out, "# OPTIONS INHERITED FROM PARENT COMMANDS\n")
manPrintFlags(out, flags)
fmt.Fprintf(out, "\n")
}
}
func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
2015-08-18 22:33:41 +00:00
// something like `rootcmd subcmd1 subcmd2`
commandName := cmd.CommandPath()
// something like `rootcmd-subcmd1-subcmd2`
dashCommandName := strings.Replace(commandName, " ", "-", -1)
fillHeader(header, commandName)
2015-08-18 22:33:41 +00:00
buf := new(bytes.Buffer)
short := cmd.Short
long := cmd.Long
if len(long) == 0 {
long = short
}
manPreamble(buf, header, commandName, short, long)
2015-08-18 22:33:41 +00:00
manPrintOptions(buf, cmd)
if len(cmd.Example) > 0 {
fmt.Fprintf(buf, "# EXAMPLE\n")
fmt.Fprintf(buf, "```\n%s\n```\n", cmd.Example)
}
if hasSeeAlso(cmd) {
2015-08-18 22:33:41 +00:00
fmt.Fprintf(buf, "# SEE ALSO\n")
seealsos := make([]string, 0)
2015-08-18 22:33:41 +00:00
if cmd.HasParent() {
parentPath := cmd.Parent().CommandPath()
dashParentPath := strings.Replace(parentPath, " ", "-", -1)
seealso := fmt.Sprintf("**%s(%s)**", dashParentPath, header.Section)
seealsos = append(seealsos, seealso)
cmd.VisitParents(func(c *cobra.Command) {
if c.DisableAutoGenTag {
cmd.DisableAutoGenTag = c.DisableAutoGenTag
}
})
2015-08-18 22:33:41 +00:00
}
children := cmd.Commands()
sort.Sort(byName(children))
for _, c := range children {
if !c.IsAvailableCommand() || c.IsHelpCommand() {
2015-08-18 22:33:41 +00:00
continue
}
seealso := fmt.Sprintf("**%s-%s(%s)**", dashCommandName, c.Name(), header.Section)
seealsos = append(seealsos, seealso)
2015-08-18 22:33:41 +00:00
}
fmt.Fprintf(buf, "%s\n", strings.Join(seealsos, ", "))
2015-08-18 22:33:41 +00:00
}
if !cmd.DisableAutoGenTag {
fmt.Fprintf(buf, "# HISTORY\n%s Auto generated by spf13/cobra\n", header.Date.Format("2-Jan-2006"))
}
2015-08-18 22:33:41 +00:00
return buf.Bytes()
}