command documentation
This commit is contained in:
parent
7968a7be3d
commit
09ade754f8
25
Makefile
25
Makefile
@ -1,4 +1,8 @@
|
||||
sources = $(shell find . -name "*.go" | grep -v iniparser.gen.go | grep -v docreflect.gen.go | grep -v docreflect_test.go)
|
||||
PREFIX ?= /usr/local
|
||||
prefix ?= $(PREFIX)
|
||||
date = $(shell git show -s --format=%cs HEAD)
|
||||
version = $(date)-$(shell git rev-parse --short HEAD)
|
||||
|
||||
default: build
|
||||
|
||||
@ -6,7 +10,7 @@ lib: $(sources) iniparser.gen.go docreflect.gen.go
|
||||
go build
|
||||
go build ./tools
|
||||
|
||||
build: lib .build/wand
|
||||
build: lib .build/wand cmd/wand/readme.md
|
||||
|
||||
check: $(sources) build docreflect_test.go
|
||||
go test -count 1 ./...
|
||||
@ -46,11 +50,24 @@ docreflect_test.go: $(sources)
|
||||
.build/wand: $(sources) iniparser.gen.go docreflect.gen.go .build
|
||||
go build \
|
||||
-o .build/wand \
|
||||
-ldflags "-X main.version=$(git show -s --format=%cs HEAD)-$(shell git rev-parse --short HEAD)" \
|
||||
-ldflags "-X main.version=$(version)" \
|
||||
./cmd/wand
|
||||
|
||||
install: .build/wand
|
||||
cp .build/wand ~/bin
|
||||
.build/wand.1: $(sources) iniparser.gen.go docreflect.gen.go .build
|
||||
go run script/man/man.go $(date) $(version) ./cmd/wand > .build/wand.1
|
||||
|
||||
cmd/wand/readme.md:
|
||||
go run script/markdown/md.go 0 ./cmd/wand > cmd/wand/readme.md
|
||||
|
||||
$(prefix)/bin:
|
||||
mkdir -p $(prefix)/bin
|
||||
|
||||
$(prefix)/share/man/man1:
|
||||
mkdir -p $(prefix)/share/man/man1
|
||||
|
||||
install: .build/wand .build/wand.1 $(prefix)/bin $(prefix)/share/man/man1
|
||||
cp .build/wand $(prefix)/bin
|
||||
cp .build/wand.1 $(prefix)/share/man/man1
|
||||
|
||||
clean:
|
||||
go clean ./...
|
||||
|
||||
0
cmd/wand/readme.md
Normal file
0
cmd/wand/readme.md
Normal file
@ -2,35 +2,34 @@
|
||||
Generated with https://code.squareroundforest.org/arpio/docreflect
|
||||
*/
|
||||
|
||||
|
||||
package wand
|
||||
|
||||
import "code.squareroundforest.org/arpio/docreflect"
|
||||
|
||||
func init() {
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools", "Package tools provides tools to work with the wand library. The functions in this package serve primarily as\nthe implementation of the wand executable command.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\naccessed by the automatic help and documentation generator.\n\nThe packageName parameter specifies the package name for the generated Go code.\n\nThe gopath arguments accept any number of package, package level symbol, or struct field paths. It is\nrecommended to use package paths unless special circumstances.\n\nfunc(out, packageName, gopaths)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "Exec executes a Go function expression parameterized by the subsequent command line arguments.\n\nIt has two modes. When called with arguments, the first argument must be the function expression, and the\nrest of the arguments the command line flags and positional arguments. When no arguments are provided, it\nstarts reading from the input, and considers every line as the expected function expression followed by the\noptions and positional arguments. In the latter case, the escaping is mostly identical to that of the bash\ninput. It keeps executing the input expressions until the input is closed (Ctrl+D).\n\nfunc(o, stdin, stdout, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions", "ExecOptions represents input options for executing a function from the command line using the wand mechanism.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.CacheDir", "CacheDir specifies a custom cache dir for wand. Default: ~/.wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ClearCache", "ClearCache clears the cached artifacts resulting from a previous execution before the current execution.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "Import lists the packages required for the expression to be executed. It accepts versioned package\nspecifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will\nimport the for the expression with the specified alias or inline.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.NoCache", "NoCache causes the execution to avoid relying on the cached artifacts resulting from a previous\nexecution.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "ReplaceModule replaces imported go modules with local or other versions of the given modules. The format\nof the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Man", "Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries\nextracted by Docreflect.\n\nfunc(out, o, commandDir)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions", "ManOptions represents input options for generating man pages for a command created with wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.DateString", "DateString provides the value for the release date field in a man page.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.Version", "Version provides the value for the release version field in a man page.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Markdown", "Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by\nDocreflect.\n\nfunc(out, o, commandDir)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions", "MarkdownOptions represents input options for generating markdown documents for a command created with wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions.Level", "Level provides a default title level offset for the titles in a markdown document.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.commandReader", "\nfunc(in)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execCommandDir", "\nfunc(out, commandDir, env)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execInput", "\nfunc(o, stdin, stdout, stderr, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execInternal", "\nfunc(command, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execWand", "\nfunc(o, stdin, stdout, stderr, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execc", "\nfunc(stdin, stdout, stderr, command, args, env)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.hash", "\nfunc(expression, imports)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.printGoFile", "\nfunc(fn, expression, imports)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.readExec", "\nfunc(o, stdin, stdout, stderr)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.selfPkg", "")
|
||||
}
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools", "Package tools provides tools to work with the wand library. The functions in this package serve primarily as\nthe implementation of the wand executable command.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\naccessed by the automatic help and documentation generator.\n\nThe packageName parameter specifies the package name for the generated Go code.\n\nThe gopath arguments accept any number of package, package level symbol, or struct field paths. It is\nrecommended to use package paths unless special circumstances.\n\nfunc(out, packageName, gopaths)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "Exec executes a Go function expression parameterized by the subsequent command line arguments.\n\nIt has two modes. When called with arguments, the first argument must be the function expression, and the\nrest of the arguments the command line flags and positional arguments. When no arguments are provided, it\nstarts reading from the input, and considers every line as the expected function expression followed by the\noptions and positional arguments. In the latter case, the escaping is mostly identical to that of the bash\ninput. It keeps executing the input expressions until the input is closed (Ctrl+D).\n\nfunc(o, stdin, stdout, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions", "ExecOptions represents input options for executing a function from the command line using the wand mechanism.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.CacheDir", "CacheDir specifies a custom cache dir for wand. Default: ~/.wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ClearCache", "ClearCache clears the cached artifacts resulting from a previous execution before the current execution.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "Import lists the packages required for the expression to be executed. It accepts versioned package\nspecifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will\nimport the for the expression with the specified alias or inline.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.NoCache", "NoCache causes the execution to avoid relying on the cached artifacts resulting from a previous\nexecution.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "ReplaceModule replaces imported go modules with local or other versions of the given modules. The format\nof the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Man", "Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries\nextracted by Docreflect.\n\nfunc(out, o, commandDir)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions", "ManOptions represents input options for generating man pages for a command created with wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.DateString", "DateString provides the value for the release date field in a man page.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.Version", "Version provides the value for the release version field in a man page.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Markdown", "Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by\nDocreflect.\n\nfunc(out, o, commandDir)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions", "MarkdownOptions represents input options for generating markdown documents for a command created with wand.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions.Level", "Level provides a default title level offset for the titles in a markdown document.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.commandReader", "\nfunc(in)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execCommandDir", "\nfunc(out, commandDir, env)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execInput", "\nfunc(o, stdin, stdout, stderr, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execInternal", "\nfunc(command, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execWand", "\nfunc(o, stdin, stdout, stderr, args)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execc", "\nfunc(stdin, stdout, stderr, command, args, env)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.hash", "\nfunc(expression, imports)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.printGoFile", "\nfunc(fn, expression, imports)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.readExec", "\nfunc(o, stdin, stdout, stderr)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/tools.selfPkg", "")
|
||||
}
|
||||
@ -2,22 +2,21 @@
|
||||
Generated with https://code.squareroundforest.org/arpio/docreflect
|
||||
*/
|
||||
|
||||
|
||||
package wand
|
||||
|
||||
import "code.squareroundforest.org/arpio/docreflect"
|
||||
|
||||
func init() {
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Bar", "\nfunc(out, a, b, c)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Baz", "\nfunc(o)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.CustomHelp", "\nfunc(o)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Foo", "Foo sums three numbers.\nIt prints the sum to stdout.\n\nThe input numbers can be any integer.\n\nfunc(a, b, c)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.OptionWithHelp", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.OptionWithHelp.Help", "Custom help.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Bar", "Bars, any number.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Duration", "Duration is another option.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Foo", "Foo is an option.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Some", "Some is an option of any type.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Time", "Time is the third option here.\n")
|
||||
}
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Bar", "\nfunc(out, a, b, c)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Baz", "\nfunc(o)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.CustomHelp", "\nfunc(o)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Foo", "Foo sums three numbers.\nIt prints the sum to stdout.\n\nThe input numbers can be any integer.\n\nfunc(a, b, c)")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.OptionWithHelp", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.OptionWithHelp.Help", "Custom help.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options", "")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Bar", "Bars, any number.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Duration", "Duration is another option.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Foo", "Foo is an option.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Some", "Some is an option of any type.\n")
|
||||
docreflect.Register("code.squareroundforest.org/arpio/wand/internal/tests/testlib.Options.Time", "Time is the third option here.\n")
|
||||
}
|
||||
18
script/man/man.go
Normal file
18
script/man/man.go
Normal file
@ -0,0 +1,18 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"code.squareroundforest.org/arpio/wand/tools"
|
||||
"log"
|
||||
"os"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) < 4 {
|
||||
log.Fatalln("expected release date, version and command dir")
|
||||
}
|
||||
|
||||
options := tools.ManOptions{DateString: os.Args[1], Version: os.Args[2]}
|
||||
if err := tools.Man(os.Stdout, options, os.Args[3]); err != nil {
|
||||
log.Fatalln(err)
|
||||
}
|
||||
}
|
||||
24
script/markdown/md.go
Normal file
24
script/markdown/md.go
Normal file
@ -0,0 +1,24 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"code.squareroundforest.org/arpio/wand/tools"
|
||||
"log"
|
||||
"os"
|
||||
"strconv"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) < 3 {
|
||||
log.Fatalln("default level and command dir are missing")
|
||||
}
|
||||
|
||||
level, err := strconv.ParseInt(os.Args[1], 10, 64)
|
||||
if err != nil {
|
||||
log.Fatalln(err)
|
||||
}
|
||||
|
||||
options := tools.MarkdownOptions{Level: int(level)}
|
||||
if err := tools.Markdown(os.Stdout, options, os.Args[2]); err != nil {
|
||||
log.Fatalln(err)
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user