Merge pull request #830 from saschagrunert/docs-gen
Add markdown and man page docs generation methodsmain
Audrius Butkevicius
5 years ago
committed by
GitHub
commit
2c477e720e
@ -0,0 +1,146 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"fmt"
|
||||
"io"
|
||||
"sort"
|
||||
"strings"
|
||||
"text/template"
|
||||
|
||||
"github.com/cpuguy83/go-md2man/md2man"
|
||||
)
|
||||
|
||||
// ToMarkdown creates a markdown string for the `*App`
|
||||
// The function errors if either parsing or writing of the string fails.
|
||||
func (a *App) ToMarkdown() (string, error) {
|
||||
var w bytes.Buffer
|
||||
if err := a.writeDocTemplate(&w); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return w.String(), nil
|
||||
}
|
||||
|
||||
// ToMan creates a man page string for the `*App`
|
||||
// The function errors if either parsing or writing of the string fails.
|
||||
func (a *App) ToMan() (string, error) {
|
||||
var w bytes.Buffer
|
||||
if err := a.writeDocTemplate(&w); err != nil {
|
||||
return "", err
|
||||
}
|
||||
man := md2man.Render(w.Bytes())
|
||||
return string(man), nil
|
||||
}
|
||||
|
||||
type cliTemplate struct {
|
||||
App *App
|
||||
Date string
|
||||
Commands []string
|
||||
GlobalArgs []string
|
||||
SynopsisArgs []string
|
||||
}
|
||||
|
||||
func (a *App) writeDocTemplate(w io.Writer) error {
|
||||
const name = "cli"
|
||||
t, err := template.New(name).Parse(MarkdownDocTemplate)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return t.ExecuteTemplate(w, name, &cliTemplate{
|
||||
App: a,
|
||||
Commands: prepareCommands(a.Commands, 0),
|
||||
GlobalArgs: prepareArgsWithValues(a.Flags),
|
||||
SynopsisArgs: prepareArgsSynopsis(a.Flags),
|
||||
})
|
||||
}
|
||||
|
||||
func prepareCommands(commands []Command, level int) []string {
|
||||
coms := []string{}
|
||||
for i := range commands {
|
||||
command := &commands[i]
|
||||
usage := ""
|
||||
if command.Usage != "" {
|
||||
usage = command.Usage
|
||||
}
|
||||
|
||||
prepared := fmt.Sprintf("%s %s\n\n%s\n",
|
||||
strings.Repeat("#", level+2),
|
||||
strings.Join(command.Names(), ", "),
|
||||
usage,
|
||||
)
|
||||
|
||||
flags := prepareArgsWithValues(command.Flags)
|
||||
if len(flags) > 0 {
|
||||
prepared += fmt.Sprintf("\n%s", strings.Join(flags, "\n"))
|
||||
}
|
||||
|
||||
coms = append(coms, prepared)
|
||||
|
||||
// recursevly iterate subcommands
|
||||
if len(command.Subcommands) > 0 {
|
||||
coms = append(
|
||||
coms,
|
||||
prepareCommands(command.Subcommands, level+1)...,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
return coms
|
||||
}
|
||||
|
||||
func prepareArgsWithValues(flags []Flag) []string {
|
||||
return prepareFlags(flags, ", ", "**", "**", `""`, true)
|
||||
}
|
||||
|
||||
func prepareArgsSynopsis(flags []Flag) []string {
|
||||
return prepareFlags(flags, "|", "[", "]", "[value]", false)
|
||||
}
|
||||
|
||||
func prepareFlags(
|
||||
flags []Flag,
|
||||
sep, opener, closer, value string,
|
||||
addDetails bool,
|
||||
) []string {
|
||||
args := []string{}
|
||||
for _, f := range flags {
|
||||
flag, ok := f.(DocGenerationFlag)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
modifiedArg := opener
|
||||
for _, s := range strings.Split(flag.GetName(), ",") {
|
||||
trimmed := strings.TrimSpace(s)
|
||||
if len(modifiedArg) > len(opener) {
|
||||
modifiedArg += sep
|
||||
}
|
||||
if len(trimmed) > 1 {
|
||||
modifiedArg += fmt.Sprintf("--%s", trimmed)
|
||||
} else {
|
||||
modifiedArg += fmt.Sprintf("-%s", trimmed)
|
||||
}
|
||||
}
|
||||
modifiedArg += closer
|
||||
if flag.TakesValue() {
|
||||
modifiedArg += fmt.Sprintf("=%s", value)
|
||||
}
|
||||
|
||||
if addDetails {
|
||||
modifiedArg += flagDetails(flag)
|
||||
}
|
||||
|
||||
args = append(args, modifiedArg+"\n")
|
||||
|
||||
}
|
||||
sort.Strings(args)
|
||||
return args
|
||||
}
|
||||
|
||||
// flagDetails returns a string containing the flags metadata
|
||||
func flagDetails(flag DocGenerationFlag) string {
|
||||
description := flag.GetUsage()
|
||||
value := flag.GetValue()
|
||||
if value != "" {
|
||||
description += " (default: " + value + ")"
|
||||
}
|
||||
return ": " + description
|
||||
}
|
||||
@ -0,0 +1,115 @@
|
||||
package cli
|
||||
|
||||
import (
|
||||
"io/ioutil"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func testApp() *App {
|
||||
app := NewApp()
|
||||
app.Name = "greet"
|
||||
app.Flags = []Flag{
|
||||
StringFlag{
|
||||
Name: "socket, s",
|
||||
Usage: "some usage text",
|
||||
Value: "value",
|
||||
},
|
||||
StringFlag{Name: "flag, fl, f"},
|
||||
BoolFlag{
|
||||
Name: "another-flag, b",
|
||||
Usage: "another usage text",
|
||||
},
|
||||
}
|
||||
app.Commands = []Command{{
|
||||
Aliases: []string{"c"},
|
||||
Flags: []Flag{
|
||||
StringFlag{Name: "flag, fl, f"},
|
||||
BoolFlag{
|
||||
Name: "another-flag, b",
|
||||
Usage: "another usage text",
|
||||
},
|
||||
},
|
||||
Name: "config",
|
||||
Usage: "another usage test",
|
||||
Subcommands: []Command{{
|
||||
Aliases: []string{"s", "ss"},
|
||||
Flags: []Flag{
|
||||
StringFlag{Name: "sub-flag, sub-fl, s"},
|
||||
BoolFlag{
|
||||
Name: "sub-command-flag, s",
|
||||
Usage: "some usage text",
|
||||
},
|
||||
},
|
||||
Name: "sub-config",
|
||||
Usage: "another usage test",
|
||||
}},
|
||||
}, {
|
||||
Aliases: []string{"i", "in"},
|
||||
Name: "info",
|
||||
Usage: "retrieve generic information",
|
||||
}, {
|
||||
Name: "some-command",
|
||||
}}
|
||||
app.UsageText = "app [first_arg] [second_arg]"
|
||||
app.Usage = "Some app"
|
||||
app.Author = "Harrison"
|
||||
app.Email = "harrison@lolwut.com"
|
||||
app.Authors = []Author{{Name: "Oliver Allen", Email: "oliver@toyshop.com"}}
|
||||
return app
|
||||
}
|
||||
|
||||
func expectFileContent(t *testing.T, file, expected string) {
|
||||
data, err := ioutil.ReadFile(file)
|
||||
expect(t, err, nil)
|
||||
expect(t, string(data), expected)
|
||||
}
|
||||
|
||||
func TestToMarkdownFull(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
|
||||
// When
|
||||
res, err := app.ToMarkdown()
|
||||
|
||||
// Then
|
||||
expect(t, err, nil)
|
||||
expectFileContent(t, "testdata/expected-doc-full.md", res)
|
||||
}
|
||||
|
||||
func TestToMarkdownNoFlags(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
app.Flags = nil
|
||||
|
||||
// When
|
||||
res, err := app.ToMarkdown()
|
||||
|
||||
// Then
|
||||
expect(t, err, nil)
|
||||
expectFileContent(t, "testdata/expected-doc-no-flags.md", res)
|
||||
}
|
||||
|
||||
func TestToMarkdownNoCommands(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
app.Commands = nil
|
||||
|
||||
// When
|
||||
res, err := app.ToMarkdown()
|
||||
|
||||
// Then
|
||||
expect(t, err, nil)
|
||||
expectFileContent(t, "testdata/expected-doc-no-commands.md", res)
|
||||
}
|
||||
|
||||
func TestToMan(t *testing.T) {
|
||||
// Given
|
||||
app := testApp()
|
||||
|
||||
// When
|
||||
res, err := app.ToMan()
|
||||
|
||||
// Then
|
||||
expect(t, err, nil)
|
||||
expectFileContent(t, "testdata/expected-doc-full.man", res)
|
||||
}
|
||||
@ -0,0 +1,107 @@
|
||||
package cli
|
||||
|
||||
// AppHelpTemplate is the text template for the Default help topic.
|
||||
// cli.go uses text/template to render templates. You can
|
||||
// render custom help text by setting this variable.
|
||||
var AppHelpTemplate = `NAME:
|
||||
{{.Name}}{{if .Usage}} - {{.Usage}}{{end}}
|
||||
|
||||
USAGE:
|
||||
{{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} {{if .VisibleFlags}}[global options]{{end}}{{if .Commands}} command [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Version}}{{if not .HideVersion}}
|
||||
|
||||
VERSION:
|
||||
{{.Version}}{{end}}{{end}}{{if .Description}}
|
||||
|
||||
DESCRIPTION:
|
||||
{{.Description}}{{end}}{{if len .Authors}}
|
||||
|
||||
AUTHOR{{with $length := len .Authors}}{{if ne 1 $length}}S{{end}}{{end}}:
|
||||
{{range $index, $author := .Authors}}{{if $index}}
|
||||
{{end}}{{$author}}{{end}}{{end}}{{if .VisibleCommands}}
|
||||
|
||||
COMMANDS:{{range .VisibleCategories}}{{if .Name}}
|
||||
|
||||
{{.Name}}:{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
|
||||
|
||||
GLOBAL OPTIONS:
|
||||
{{range $index, $option := .VisibleFlags}}{{if $index}}
|
||||
{{end}}{{$option}}{{end}}{{end}}{{if .Copyright}}
|
||||
|
||||
COPYRIGHT:
|
||||
{{.Copyright}}{{end}}
|
||||
`
|
||||
|
||||
// CommandHelpTemplate is the text template for the command help topic.
|
||||
// cli.go uses text/template to render templates. You can
|
||||
// render custom help text by setting this variable.
|
||||
var CommandHelpTemplate = `NAME:
|
||||
{{.HelpName}} - {{.Usage}}
|
||||
|
||||
USAGE:
|
||||
{{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}}{{if .VisibleFlags}} [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Category}}
|
||||
|
||||
CATEGORY:
|
||||
{{.Category}}{{end}}{{if .Description}}
|
||||
|
||||
DESCRIPTION:
|
||||
{{.Description}}{{end}}{{if .VisibleFlags}}
|
||||
|
||||
OPTIONS:
|
||||
{{range .VisibleFlags}}{{.}}
|
||||
{{end}}{{end}}
|
||||
`
|
||||
|
||||
// SubcommandHelpTemplate is the text template for the subcommand help topic.
|
||||
// cli.go uses text/template to render templates. You can
|
||||
// render custom help text by setting this variable.
|
||||
var SubcommandHelpTemplate = `NAME:
|
||||
{{.HelpName}} - {{if .Description}}{{.Description}}{{else}}{{.Usage}}{{end}}
|
||||
|
||||
USAGE:
|
||||
{{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}} command{{if .VisibleFlags}} [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}
|
||||
|
||||
COMMANDS:{{range .VisibleCategories}}{{if .Name}}
|
||||
|
||||
{{.Name}}:{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
|
||||
|
||||
OPTIONS:
|
||||
{{range .VisibleFlags}}{{.}}
|
||||
{{end}}{{end}}
|
||||
`
|
||||
|
||||
var MarkdownDocTemplate = `% {{ .App.Name }}(8) {{ .App.Description }}
|
||||
|
||||
% {{ .App.Author }}
|
||||
|
||||
# NAME
|
||||
|
||||
{{ .App.Name }}{{ if .App.Usage }} - {{ .App.Usage }}{{ end }}
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
{{ .App.Name }}
|
||||
{{ if .SynopsisArgs }}
|
||||
` + "```" + `
|
||||
{{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + `
|
||||
{{ end }}{{ if .App.UsageText }}
|
||||
# DESCRIPTION
|
||||
|
||||
{{ .App.UsageText }}
|
||||
{{ end }}
|
||||
**Usage**:
|
||||
|
||||
` + "```" + `
|
||||
{{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
` + "```" + `
|
||||
{{ if .GlobalArgs }}
|
||||
# GLOBAL OPTIONS
|
||||
{{ range $v := .GlobalArgs }}
|
||||
{{ $v }}{{ end }}
|
||||
{{ end }}{{ if .Commands }}
|
||||
# COMMANDS
|
||||
{{ range $v := .Commands }}
|
||||
{{ $v }}{{ end }}{{ end }}`
|
||||
@ -0,0 +1,80 @@
|
||||
.nh
|
||||
.TH greet(8)
|
||||
|
||||
.SH Harrison
|
||||
|
||||
.SH NAME
|
||||
.PP
|
||||
greet \- Some app
|
||||
|
||||
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
greet
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
[\-\-another\-flag|\-b]
|
||||
[\-\-flag|\-\-fl|\-f]=[value]
|
||||
[\-\-socket|\-s]=[value]
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
app [first\_arg] [second\_arg]
|
||||
|
||||
.PP
|
||||
\fBUsage\fP:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
|
||||
.fi
|
||||
.RE
|
||||
|
||||
|
||||
.SH GLOBAL OPTIONS
|
||||
.PP
|
||||
\fB\-\-another\-flag, \-b\fP: another usage text
|
||||
|
||||
.PP
|
||||
\fB\-\-flag, \-\-fl, \-f\fP="":
|
||||
|
||||
.PP
|
||||
\fB\-\-socket, \-s\fP="": some usage text (default: value)
|
||||
|
||||
|
||||
.SH COMMANDS
|
||||
.SH config, c
|
||||
.PP
|
||||
another usage test
|
||||
|
||||
.PP
|
||||
\fB\-\-another\-flag, \-b\fP: another usage text
|
||||
|
||||
.PP
|
||||
\fB\-\-flag, \-\-fl, \-f\fP="":
|
||||
|
||||
.SS sub\-config, s, ss
|
||||
.PP
|
||||
another usage test
|
||||
|
||||
.PP
|
||||
\fB\-\-sub\-command\-flag, \-s\fP: some usage text
|
||||
|
||||
.PP
|
||||
\fB\-\-sub\-flag, \-\-sub\-fl, \-s\fP="":
|
||||
|
||||
.SH info, i, in
|
||||
.PP
|
||||
retrieve generic information
|
||||
|
||||
.SH some\-command
|
||||
@ -0,0 +1,62 @@
|
||||
% greet(8)
|
||||
|
||||
% Harrison
|
||||
|
||||
# NAME
|
||||
|
||||
greet - Some app
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
greet
|
||||
|
||||
```
|
||||
[--another-flag|-b]
|
||||
[--flag|--fl|-f]=[value]
|
||||
[--socket|-s]=[value]
|
||||
```
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
**--socket, -s**="": some usage text (default: value)
|
||||
|
||||
|
||||
# COMMANDS
|
||||
|
||||
## config, c
|
||||
|
||||
another usage test
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
### sub-config, s, ss
|
||||
|
||||
another usage test
|
||||
|
||||
**--sub-command-flag, -s**: some usage text
|
||||
|
||||
**--sub-flag, --sub-fl, -s**="":
|
||||
|
||||
## info, i, in
|
||||
|
||||
retrieve generic information
|
||||
|
||||
## some-command
|
||||
|
||||
|
||||
@ -0,0 +1,36 @@
|
||||
% greet(8)
|
||||
|
||||
% Harrison
|
||||
|
||||
# NAME
|
||||
|
||||
greet - Some app
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
greet
|
||||
|
||||
```
|
||||
[--another-flag|-b]
|
||||
[--flag|--fl|-f]=[value]
|
||||
[--socket|-s]=[value]
|
||||
```
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
```
|
||||
|
||||
# GLOBAL OPTIONS
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
**--socket, -s**="": some usage text (default: value)
|
||||
|
||||
@ -0,0 +1,47 @@
|
||||
% greet(8)
|
||||
|
||||
% Harrison
|
||||
|
||||
# NAME
|
||||
|
||||
greet - Some app
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
greet
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
app [first_arg] [second_arg]
|
||||
|
||||
**Usage**:
|
||||
|
||||
```
|
||||
greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
|
||||
```
|
||||
|
||||
# COMMANDS
|
||||
|
||||
## config, c
|
||||
|
||||
another usage test
|
||||
|
||||
**--another-flag, -b**: another usage text
|
||||
|
||||
**--flag, --fl, -f**="":
|
||||
|
||||
### sub-config, s, ss
|
||||
|
||||
another usage test
|
||||
|
||||
**--sub-command-flag, -s**: some usage text
|
||||
|
||||
**--sub-flag, --sub-fl, -s**="":
|
||||
|
||||
## info, i, in
|
||||
|
||||
retrieve generic information
|
||||
|
||||
## some-command
|
||||
|
||||
|
||||
Loading…
Reference in new issue