vinchent/cobra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #228 from garthk/fix-doc-generation

Browse Source 
Fix doc generation and its documentation
This commit is contained in:
Eric Paris
2016-01-16 22:09:38 -05:00
parent 9c93009019 356750645f
commit 8e91712f17
4 changed files with 37 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/man_docs.go
View File

@ -18,6 +18,7 @@ import (
"fmt" "fmt"
"io" "io"
"os" "os"
"path/filepath"
"sort" "sort"
"strings" "strings"
"time" "time"
@ -46,8 +47,8 @@ func GenManTree(cmd *cobra.Command, header *GenManHeader, dir string) error {
} }
needToResetTitle := header.Title == "" needToResetTitle := header.Title == ""
filename := cmd.CommandPath() basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".1"
filename = dir + strings.Replace(filename, " ", "-", -1) + ".1" filename := filepath.Join(dir, basename)
f, err := os.Create(filename) f, err := os.Create(filename)
if err != nil { if err != nil {
return err return err

3
doc/man_docs.md
View File

@ -7,6 +7,7 @@ package main
import ( import (
"github.com/spf13/cobra" "github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
) )
func main() { func main() {
@ -18,7 +19,7 @@ func main() {
Title: "MINE", Title: "MINE",
Section: "3", Section: "3",
} }
cmd.GenManTree(header, "/tmp") doc.GenManTree(cmd, header, "/tmp")
} }
``` ```

5
doc/md_docs.go
View File

@ -17,6 +17,7 @@ import (
"fmt" "fmt"
"io" "io"
"os" "os"
"path/filepath"
"sort" "sort"
"strings" "strings"
"time" "time"
@ -156,8 +157,8 @@ func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHa
} }
} }
filename := cmd.CommandPath() basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
filename = dir + strings.Replace(filename, " ", "_", -1) + ".md" filename := filepath.Join(dir, basename)
f, err := os.Create(filename) f, err := os.Create(filename)
if err != nil { if err != nil {
return err return err

35
doc/md_docs.md
View File

@ -1,5 +1,26 @@
# Generating Markdown Docs For Your Own cobra.Command # Generating Markdown Docs For Your Own cobra.Command
Generating man pages from a cobra command is incredibly easy. An example is as follows:
```go
package main
import (
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
func main() {
cmd := &cobra.Command{
Use: "test",
Short: "my test program",
}
doc.GenMarkdownTree(cmd, "/tmp")
}
```
That will get you a Markdown document `/tmp/test.md`
## Generate markdown docs for the entire command tree ## Generate markdown docs for the entire command tree
This program can actually generate docs for the kubectl command in the kubernetes project This program can actually generate docs for the kubectl command in the kubernetes project
@ -11,13 +32,15 @@ import (
"io/ioutil" "io/ioutil"
"os" "os"
"github.com/GoogleCloudPlatform/kubernetes/pkg/kubectl/cmd" kubectlcmd "k8s.io/kubernetes/pkg/kubectl/cmd"
"github.com/spf13/cobra/cobra" cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
"github.com/spf13/cobra/doc"
) )
func main() { func main() {
kubectl := cmd.NewFactory(nil).NewKubectlCommand(os.Stdin, ioutil.Discard, ioutil.Discard) cmd := kubectlcmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
doc.GenMarkdownTree(kubectl, "./") doc.GenMarkdownTree(cmd, "./")
} }
``` ```
@ -40,13 +63,13 @@ Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks
```go ```go
func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error { func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
//... //...
} }
``` ```
```go ```go
func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error { func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
//... //...
} }
``` ```