STACKITGit/cli
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Allow accessing Cobra built-in doc generation features

Browse source 
Setting GH_COBRA allows access to Cobra's built-in implementation of generating man pages and markdown trees. This is useful for testing and comparing our overrides against Cobra's own logic.
This commit is contained in:
Mislav Marohnić 2022-11-09 17:30:32 +01:00
parent b3aeaf6c2e
commit 278ff59fce
No known key found for this signature in database
4 changed files with 39 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

21
internal/docs/man.go
View file

@ -13,6 +13,7 @@ import (
"github.com/cli/cli/v2/pkg/cmd/root"
"github.com/cpuguy83/go-md2man/v2/md2man"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
"github.com/spf13/pflag"
)
@ -22,20 +23,26 @@ import (
// 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, dir string) error {
return GenManTreeFromOpts(cmd, GenManTreeOptions{
if os.Getenv("GH_COBRA") != "" {
return doc.GenManTreeFromOpts(cmd, doc.GenManTreeOptions{
Path: dir,
CommandSeparator: "-",
})
}
return genManTreeFromOpts(cmd, GenManTreeOptions{
Path: dir,
CommandSeparator: "-",
})
}
// GenManTreeFromOpts generates a man page for the command and all descendants.
// genManTreeFromOpts generates a man page for the command and all descendants.
// The pages are written to the opts.Path directory.
func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
func genManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
continue
}
if err := GenManTreeFromOpts(c, opts); err != nil {
if err := genManTreeFromOpts(c, opts); err != nil {
return err
}
}
@ -58,7 +65,7 @@ func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
versionString = "GitHub CLI " + v
}
return GenMan(cmd, &GenManHeader{
return renderMan(cmd, &GenManHeader{
Section: section,
Source: versionString,
Manual: "GitHub CLI manual",
@ -83,9 +90,9 @@ type GenManHeader struct {
Manual string
}
// GenMan will generate a man page for the given command and write it to
// renderMan 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 {
func renderMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error {
if err := fillHeader(header, cmd.CommandPath()); err != nil {
return err
}

8
internal/docs/man_test.go
View file

@ -24,7 +24,7 @@ func TestGenManDoc(t *testing.T) {
// We generate on a subcommand so we have both subcommands and parents
buf := new(bytes.Buffer)
if err := GenMan(echoCmd, header, buf); err != nil {
if err := renderMan(echoCmd, header, buf); err != nil {
t.Fatal(err)
}
output := buf.String()
@ -58,7 +58,7 @@ func TestGenManNoHiddenParents(t *testing.T) {
defer func() { f.Hidden = false }()
}
buf := new(bytes.Buffer)
if err := GenMan(echoCmd, header, buf); err != nil {
if err := renderMan(echoCmd, header, buf); err != nil {
t.Fatal(err)
}
output := buf.String()
@ -89,7 +89,7 @@ func TestGenManSeeAlso(t *testing.T) {
buf := new(bytes.Buffer)
header := &GenManHeader{}
if err := GenMan(rootCmd, header, buf); err != nil {
if err := renderMan(rootCmd, header, buf); err != nil {
t.Fatal(err)
}
scanner := bufio.NewScanner(buf)
@ -154,7 +154,7 @@ func BenchmarkGenManToFile(b *testing.B) {
b.ResetTimer()
for i := 0; i < b.N; i++ {
if err := GenMan(rootCmd, nil, file); err != nil {
if err := renderMan(rootCmd, nil, file); err != nil {
b.Fatal(err)
}
}

28
internal/docs/markdown.go
View file

@ -10,6 +10,7 @@ import (
"github.com/cli/cli/v2/pkg/cmd/root"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
"github.com/spf13/pflag"
)
@ -79,13 +80,8 @@ func printFlagsHTML(w io.Writer, fs *pflag.FlagSet) error {
return tpl.Execute(w, flags)
}
// GenMarkdown creates markdown output.
func GenMarkdown(cmd *cobra.Command, w io.Writer) error {
return GenMarkdownCustom(cmd, w, func(s string) string { return s })
}
// GenMarkdownCustom creates custom markdown output.
func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
// genMarkdownCustom creates custom markdown output.
func genMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
fmt.Fprint(w, "{% raw %}")
fmt.Fprintf(w, "## %s\n\n", cmd.CommandPath())
@ -128,21 +124,13 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
return nil
}
// GenMarkdownTree will generate a markdown 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 GenMarkdownTree(cmd *cobra.Command, dir string) error {
identity := func(s string) string { return s }
emptyStr := func(s string) string { return "" }
return GenMarkdownTreeCustom(cmd, dir, emptyStr, identity)
}
// GenMarkdownTreeCustom is the same as GenMarkdownTree, but
// with custom filePrepender and linkHandler.
func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
if os.Getenv("GH_COBRA") != "" {
return doc.GenMarkdownTreeCustom(cmd, dir, filePrepender, linkHandler)
}
for _, c := range cmd.Commands() {
_, forceGeneration := c.Annotations["markdown:generate"]
if c.Hidden && !forceGeneration {
@ -164,7 +152,7 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
return err
}
if err := GenMarkdownCustom(cmd, f, linkHandler); err != nil {
if err := genMarkdownCustom(cmd, f, linkHandler); err != nil {
return err
}
return nil

18
internal/docs/markdown_test.go
View file

@ -10,9 +10,11 @@ import (
)
func TestGenMdDoc(t *testing.T) {
linkHandler := func(s string) string { return s }
// We generate on subcommand so we have both subcommands and parents.
buf := new(bytes.Buffer)
if err := GenMarkdown(echoCmd, buf); err != nil {
if err := genMarkdownCustom(echoCmd, buf, linkHandler); err != nil {
t.Fatal(err)
}
output := buf.String()
@ -28,9 +30,11 @@ func TestGenMdDoc(t *testing.T) {
}
func TestGenMdDocWithNoLongOrSynopsis(t *testing.T) {
linkHandler := func(s string) string { return s }
// We generate on subcommand so we have both subcommands and parents.
buf := new(bytes.Buffer)
if err := GenMarkdown(dummyCmd, buf); err != nil {
if err := genMarkdownCustom(dummyCmd, buf, linkHandler); err != nil {
t.Fatal(err)
}
output := buf.String()
@ -42,6 +46,8 @@ func TestGenMdDocWithNoLongOrSynopsis(t *testing.T) {
}
func TestGenMdNoHiddenParents(t *testing.T) {
linkHandler := func(s string) string { return s }
// We generate on subcommand so we have both subcommands and parents.
for _, name := range []string{"rootflag", "strtwo"} {
f := rootCmd.PersistentFlags().Lookup(name)
@ -49,7 +55,7 @@ func TestGenMdNoHiddenParents(t *testing.T) {
defer func() { f.Hidden = false }()
}
buf := new(bytes.Buffer)
if err := GenMarkdown(echoCmd, buf); err != nil {
if err := genMarkdownCustom(echoCmd, buf, linkHandler); err != nil {
t.Fatal(err)
}
output := buf.String()
@ -72,7 +78,7 @@ func TestGenMdTree(t *testing.T) {
}
defer os.RemoveAll(tmpdir)
if err := GenMarkdownTree(c, tmpdir); err != nil {
if err := GenMarkdownTreeCustom(c, tmpdir, func(s string) string { return s }, func(s string) string { return s }); err != nil {
t.Fatalf("GenMarkdownTree failed: %v", err)
}
@ -88,9 +94,11 @@ func BenchmarkGenMarkdownToFile(b *testing.B) {
}
defer file.Close()
linkHandler := func(s string) string { return s }
b.ResetTimer()
for i := 0; i < b.N; i++ {
if err := GenMarkdown(rootCmd, file); err != nil {
if err := genMarkdownCustom(rootCmd, file, linkHandler); err != nil {
b.Fatal(err)
}
}