mirror of
https://github.com/spf13/cobra
synced 2024-08-23 17:26:33 +00:00
187 lines
5.2 KiB
Go
187 lines
5.2 KiB
Go
// Copyright 2013-2023 The Cobra Authors
|
|
//
|
|
// 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 (
|
|
"bytes"
|
|
"fmt"
|
|
"io"
|
|
"os"
|
|
"path/filepath"
|
|
"sort"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
func printOptionsReST(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
|
|
flags := cmd.NonInheritedFlags()
|
|
flags.SetOutput(buf)
|
|
if flags.HasAvailableFlags() {
|
|
buf.WriteString("Options\n")
|
|
buf.WriteString("~~~~~~~\n\n::\n\n")
|
|
flags.PrintDefaults()
|
|
buf.WriteString("\n")
|
|
}
|
|
|
|
parentFlags := cmd.InheritedFlags()
|
|
parentFlags.SetOutput(buf)
|
|
if parentFlags.HasAvailableFlags() {
|
|
buf.WriteString("Options inherited from parent commands\n")
|
|
buf.WriteString("~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n")
|
|
parentFlags.PrintDefaults()
|
|
buf.WriteString("\n")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// defaultLinkHandler for default ReST hyperlink markup
|
|
func defaultLinkHandler(name, ref string) string {
|
|
return fmt.Sprintf("`%s <%s.rst>`_", name, ref)
|
|
}
|
|
|
|
// GenReST creates reStructured Text output.
|
|
func GenReST(cmd *cobra.Command, w io.Writer) error {
|
|
return GenReSTCustom(cmd, w, defaultLinkHandler)
|
|
}
|
|
|
|
// GenReSTCustom creates custom reStructured Text output.
|
|
func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string, string) string) error {
|
|
cmd.InitDefaultHelpCmd()
|
|
cmd.InitDefaultHelpFlag()
|
|
|
|
buf := new(bytes.Buffer)
|
|
name := cmd.CommandPath()
|
|
|
|
short := cmd.Short
|
|
long := cmd.Long
|
|
if len(long) == 0 {
|
|
long = short
|
|
}
|
|
ref := strings.ReplaceAll(name, " ", "_")
|
|
|
|
buf.WriteString(".. _" + ref + ":\n\n")
|
|
buf.WriteString(name + "\n")
|
|
buf.WriteString(strings.Repeat("-", len(name)) + "\n\n")
|
|
buf.WriteString(short + "\n\n")
|
|
buf.WriteString("Synopsis\n")
|
|
buf.WriteString("~~~~~~~~\n\n")
|
|
buf.WriteString("\n" + long + "\n\n")
|
|
|
|
if cmd.Runnable() {
|
|
buf.WriteString(fmt.Sprintf("::\n\n %s\n\n", cmd.UseLine()))
|
|
}
|
|
|
|
if len(cmd.Example) > 0 {
|
|
buf.WriteString("Examples\n")
|
|
buf.WriteString("~~~~~~~~\n\n")
|
|
buf.WriteString(fmt.Sprintf("::\n\n%s\n\n", indentString(cmd.Example, " ")))
|
|
}
|
|
|
|
if err := printOptionsReST(buf, cmd, name); err != nil {
|
|
return err
|
|
}
|
|
if hasSeeAlso(cmd) {
|
|
buf.WriteString("SEE ALSO\n")
|
|
buf.WriteString("~~~~~~~~\n\n")
|
|
if cmd.HasParent() {
|
|
parent := cmd.Parent()
|
|
pname := parent.CommandPath()
|
|
ref = strings.ReplaceAll(pname, " ", "_")
|
|
buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(pname, ref), parent.Short))
|
|
cmd.VisitParents(func(c *cobra.Command) {
|
|
if c.DisableAutoGenTag {
|
|
cmd.DisableAutoGenTag = c.DisableAutoGenTag
|
|
}
|
|
})
|
|
}
|
|
|
|
children := cmd.Commands()
|
|
sort.Sort(byName(children))
|
|
|
|
for _, child := range children {
|
|
if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
|
|
continue
|
|
}
|
|
cname := name + " " + child.Name()
|
|
ref = strings.ReplaceAll(cname, " ", "_")
|
|
buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(cname, ref), child.Short))
|
|
}
|
|
buf.WriteString("\n")
|
|
}
|
|
if !cmd.DisableAutoGenTag {
|
|
buf.WriteString("*Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "*\n")
|
|
}
|
|
_, err := buf.WriteTo(w)
|
|
return err
|
|
}
|
|
|
|
// GenReSTTree will generate a ReST page 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 GenReSTTree(cmd *cobra.Command, dir string) error {
|
|
emptyStr := func(s string) string { return "" }
|
|
return GenReSTTreeCustom(cmd, dir, emptyStr, defaultLinkHandler)
|
|
}
|
|
|
|
// GenReSTTreeCustom is the the same as GenReSTTree, but
|
|
// with custom filePrepender and linkHandler.
|
|
func GenReSTTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error {
|
|
for _, c := range cmd.Commands() {
|
|
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
|
|
continue
|
|
}
|
|
if err := GenReSTTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
|
|
basename := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".rst"
|
|
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 := GenReSTCustom(cmd, f, linkHandler); err != nil {
|
|
return err
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// indentString adapted from: https://github.com/kr/text/blob/main/indent.go
|
|
func indentString(s, p string) string {
|
|
var res []byte
|
|
b := []byte(s)
|
|
prefix := []byte(p)
|
|
bol := true
|
|
for _, c := range b {
|
|
if bol && c != '\n' {
|
|
res = append(res, prefix...)
|
|
}
|
|
res = append(res, c)
|
|
bol = c == '\n'
|
|
}
|
|
return string(res)
|
|
}
|