mirror
/
cobra
mirror of https://github.com/spf13/cobra.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

Fix #401 (#402) 

* doc: Add and edit docs

* doc: Add tests
This commit is contained in:
Albert Nigmatzianov 2017-04-19 14:39:58 +02:00 committed by GitHub
parent b6cb395893
commit f95d58bdf3
9 changed files with 95 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/man_docs.go
View File

@ -30,8 +30,8 @@ import (
// 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`
// 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 {
return GenManTreeFromOpts(cmd, GenManTreeOptions{

7
doc/man_docs.md
View File

@ -6,6 +6,8 @@ Generating man pages from a cobra command is incredibly easy. An example is as f
package main
import (
"log"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
@ -19,7 +21,10 @@ func main() {
Title: "MINE",
Section: "3",
}
doc.GenManTree(cmd, header, "/tmp")
err := doc.GenManTree(cmd, header, "/tmp")
if err != nil {
log.Fatal(err)
}
}
```

5
doc/man_docs_test.go
View File

@ -13,9 +13,6 @@ import (
"github.com/spf13/cobra"
)
var _ = fmt.Println
var _ = os.Stderr
func translate(in string) string {
return strings.Replace(in, "-", "\\-", -1)
}
@ -153,7 +150,7 @@ func TestGenManTree(t *testing.T) {
header := &GenManHeader{Section: "2"}
tmpdir, err := ioutil.TempDir("", "test-gen-man-tree")
if err != nil {
t.Fatalf("Failed to create tempdir: %s", err.Error())
t.Fatalf("Failed to create tmpdir: %s", err.Error())
}
defer os.RemoveAll(tmpdir)

8
doc/md_docs.go
View File

@ -52,10 +52,12 @@ func printOptions(w io.Writer, cmd *cobra.Command, name string) error {
return nil
}
// 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 {
name := cmd.CommandPath()
@ -141,6 +143,12 @@ 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 "" }

18
doc/md_docs.md
View File

@ -6,6 +6,8 @@ Generating man pages from a cobra command is incredibly easy. An example is as f
package main
import (
"log"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
@ -15,7 +17,10 @@ func main() {
Use: "test",
Short: "my test program",
}
doc.GenMarkdownTree(cmd, "/tmp")
err := doc.GenMarkdownTree(cmd, "/tmp")
if err != nil {
log.Fatal(err)
}
}
```
@ -29,6 +34,7 @@ This program can actually generate docs for the kubectl command in the kubernete
package main
import (
"log"
"io/ioutil"
"os"
@ -40,7 +46,10 @@ import (
func main() {
kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
doc.GenMarkdownTree(kubectl, "./")
err := doc.GenMarkdownTree(kubectl, "./")
if err != nil {
log.Fatal(err)
}
}
```
@ -52,7 +61,10 @@ You may wish to have more control over the output, or only generate for a single
```go
out := new(bytes.Buffer)
doc.GenMarkdown(cmd, out)
err := doc.GenMarkdown(cmd, out)
if err != nil {
log.Fatal(err)
}
```
This will write the markdown doc for ONLY "cmd" into the out, buffer.

27
doc/md_docs_test.go
View File

@ -2,14 +2,14 @@ package doc
import (
"bytes"
"fmt"
"io/ioutil"
"os"
"path/filepath"
"strings"
"testing"
)
var _ = fmt.Println
var _ = os.Stderr
"github.com/spf13/cobra"
)
func TestGenMdDoc(t *testing.T) {
c := initializeWithRootCmd()
@ -86,3 +86,22 @@ func TestGenMdNoTag(t *testing.T) {
checkStringOmits(t, found, unexpected)
}
func TestGenMdTree(t *testing.T) {
cmd := &cobra.Command{
Use: "do [OPTIONS] arg1 arg2",
}
tmpdir, err := ioutil.TempDir("", "test-gen-md-tree")
if err != nil {
t.Fatalf("Failed to create tmpdir: %s", err.Error())
}
defer os.RemoveAll(tmpdir)
if err := GenMarkdownTree(cmd, tmpdir); err != nil {
t.Fatalf("GenMarkdownTree failed: %s", err.Error())
}
if _, err := os.Stat(filepath.Join(tmpdir, "do.md")); err != nil {
t.Fatalf("Expected file 'do.md' to exist")
}
}

10
doc/yaml_docs.go
View File

@ -45,8 +45,8 @@ type cmdDoc struct {
// GenYamlTree creates yaml structured ref files 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`
// 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 GenYamlTree(cmd *cobra.Command, dir string) error {
identity := func(s string) string { return s }
@ -54,7 +54,7 @@ func GenYamlTree(cmd *cobra.Command, dir string) error {
return GenYamlTreeCustom(cmd, dir, emptyStr, identity)
}
// GenYamlTreeCustom creates yaml structured ref files
// GenYamlTreeCustom creates yaml structured ref files.
func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
@ -82,12 +82,12 @@ func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandle
return nil
}
// GenYaml creates yaml output
// GenYaml creates yaml output.
func GenYaml(cmd *cobra.Command, w io.Writer) error {
return GenYamlCustom(cmd, w, func(s string) string { return s })
}
// GenYamlCustom creates custom yaml output
// GenYamlCustom creates custom yaml output.
func GenYamlCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
yamlDoc := cmdDoc{}
yamlDoc.Name = cmd.CommandPath()

13
doc/yaml_docs.md
View File

@ -6,6 +6,8 @@ Generating yaml files from a cobra command is incredibly easy. An example is as
package main
import (
"log"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
@ -15,7 +17,10 @@ func main() {
Use: "test",
Short: "my test program",
}
doc.GenYamlTree(cmd, "/tmp")
err := doc.GenYamlTree(cmd, "/tmp")
if err != nil {
log.Fatal(err)
}
}
```
@ -30,6 +35,7 @@ package main
import (
"io/ioutil"
"log"
"os"
"k8s.io/kubernetes/pkg/kubectl/cmd"
@ -40,7 +46,10 @@ import (
func main() {
kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
doc.GenYamlTree(kubectl, "./")
err := doc.GenYamlTree(kubectl, "./")
if err != nil {
log.Fatal(err)
}
}
```

28
doc/yaml_docs_test.go
View File

@ -2,14 +2,14 @@ package doc
import (
"bytes"
"fmt"
"io/ioutil"
"os"
"path/filepath"
"strings"
"testing"
)
var _ = fmt.Println
var _ = os.Stderr
"github.com/spf13/cobra"
)
func TestGenYamlDoc(t *testing.T) {
c := initializeWithRootCmd()
@ -86,3 +86,23 @@ func TestGenYamlNoTag(t *testing.T) {
checkStringOmits(t, found, unexpected)
}
func TestGenYamlTree(t *testing.T) {
cmd := &cobra.Command{
Use: "do [OPTIONS] arg1 arg2",
}
tmpdir, err := ioutil.TempDir("", "test-gen-yaml-tree")
if err != nil {
t.Fatalf("Failed to create tmpdir: %s", err.Error())
}
defer os.RemoveAll(tmpdir)
if err := GenYamlTree(cmd, tmpdir); err != nil {
t.Fatalf("GenYamlTree failed: %s", err.Error())
}
if _, err := os.Stat(filepath.Join(tmpdir, "do.yaml")); err != nil {
t.Fatalf("Expected file 'do.yaml' to exist")
}
}