fix markdown generation
This commit is contained in:
parent
09ade754f8
commit
dd6be747c6
2
Makefile
2
Makefile
@ -56,7 +56,7 @@ docreflect_test.go: $(sources)
|
||||
.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:
|
||||
cmd/wand/readme.md: $(sources) docreflect.gen.go
|
||||
go run script/markdown/md.go 0 ./cmd/wand > cmd/wand/readme.md
|
||||
|
||||
$(prefix)/bin:
|
||||
|
||||
@ -0,0 +1,205 @@
|
||||
# wand
|
||||
|
||||
## Synopsis:
|
||||
|
||||
```
|
||||
wand [options]... [--] [args string]...
|
||||
wand <subcommand>
|
||||
```
|
||||
|
||||
## Description:
|
||||
|
||||
Exec executes a Go function expression parameterized by the subsequent command line arguments.
|
||||
|
||||
It has two modes. When called with arguments, the first argument must be the function expression, and the rest
|
||||
of the arguments the command line flags and positional arguments. When no arguments are provided, it starts
|
||||
reading from the input, and considers every line as the expected function expression followed by the options and
|
||||
positional arguments. In the latter case, the escaping is mostly identical to that of the bash input. It keeps
|
||||
executing the input expressions until the input is closed (Ctrl+D).
|
||||
|
||||
## Options:
|
||||
|
||||
- --cache-dir, -d string: CacheDir specifies a custom cache dir for wand. Default: ~/.wand.
|
||||
- --clear-cache, -c bool: ClearCache clears the cached artifacts resulting from a previous execution before the
|
||||
current execution.
|
||||
- --import string \[\*\]: Import lists the packages required for the expression to be executed. It accepts
|
||||
versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias=
|
||||
or .=, it will import the for the expression with the specified alias or inline.
|
||||
- --no-cache, -f bool: NoCache causes the execution to avoid relying on the cached artifacts resulting from a
|
||||
previous execution.
|
||||
- --replace-module string \[\*\]: ReplaceModule replaces imported go modules with local or other versions of the
|
||||
given modules. The format of the items is: \<module-path\>=\<replacement-module-path\>, like for the go mod edit
|
||||
-replace command.
|
||||
- --help: Show help.
|
||||
|
||||
Hints:
|
||||
|
||||
- Options marked with \[\*\] accept any number of instances.
|
||||
- Bool options can be used with implicit true values.
|
||||
- The short form of bool options can be combined. The last short form does not need to be a bool option. E.g.
|
||||
-abc=42.
|
||||
- Option values can be set both via = or just separated by space.
|
||||
|
||||
## Subcommands:
|
||||
|
||||
Show help for each subcommand by calling \<command\> help or \<command\> --help.
|
||||
|
||||
### wand docreflect
|
||||
|
||||
#### Synopsis:
|
||||
|
||||
```
|
||||
wand docreflect [options]... [--] <packageName string> [gopaths string]...
|
||||
wand docreflect <subcommand>
|
||||
```
|
||||
|
||||
#### Description:
|
||||
|
||||
Docreflect generates documentation from the go docs of a package to be included in the compiled binary and
|
||||
accessed by the automatic help and documentation generator.
|
||||
|
||||
The packageName parameter specifies the package name for the generated Go code.
|
||||
|
||||
The gopath arguments accept any number of package, package level symbol, or struct field paths. It is
|
||||
recommended to use package paths unless special circumstances.
|
||||
|
||||
#### Options:
|
||||
|
||||
- --help: Show help.
|
||||
|
||||
### wand manpages
|
||||
|
||||
#### Synopsis:
|
||||
|
||||
```
|
||||
wand manpages [options]... [--] <commandDir string>
|
||||
wand manpages <subcommand>
|
||||
```
|
||||
|
||||
#### Description:
|
||||
|
||||
Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries
|
||||
extracted by Docreflect.
|
||||
|
||||
#### Options:
|
||||
|
||||
- --date-string string: DateString provides the value for the release date field in a man page.
|
||||
- --version string: Version provides the value for the release version field in a man page.
|
||||
- --help: Show help.
|
||||
|
||||
### wand markdown
|
||||
|
||||
#### Synopsis:
|
||||
|
||||
```
|
||||
wand markdown [options]... [--] <commandDir string>
|
||||
wand markdown <subcommand>
|
||||
```
|
||||
|
||||
#### Description:
|
||||
|
||||
Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by
|
||||
Docreflect.
|
||||
|
||||
#### Options:
|
||||
|
||||
- --level int: Level provides a default title level offset for the titles in a markdown document.
|
||||
- --help: Show help.
|
||||
|
||||
### wand exec (default)
|
||||
|
||||
#### Synopsis:
|
||||
|
||||
```
|
||||
wand exec [options]... [--] [args string]...
|
||||
wand exec <subcommand>
|
||||
```
|
||||
|
||||
#### Description:
|
||||
|
||||
Exec executes a Go function expression parameterized by the subsequent command line arguments.
|
||||
|
||||
It has two modes. When called with arguments, the first argument must be the function expression, and the rest
|
||||
of the arguments the command line flags and positional arguments. When no arguments are provided, it starts
|
||||
reading from the input, and considers every line as the expected function expression followed by the options and
|
||||
positional arguments. In the latter case, the escaping is mostly identical to that of the bash input. It keeps
|
||||
executing the input expressions until the input is closed (Ctrl+D).
|
||||
|
||||
#### Options:
|
||||
|
||||
- --cache-dir, -d string: CacheDir specifies a custom cache dir for wand. Default: ~/.wand.
|
||||
- --clear-cache, -c bool: ClearCache clears the cached artifacts resulting from a previous execution before the
|
||||
current execution.
|
||||
- --import string \[\*\]: Import lists the packages required for the expression to be executed. It accepts
|
||||
versioned package specifications, or it uses the latest version. When a package spec is prefixed with alias=
|
||||
or .=, it will import the for the expression with the specified alias or inline.
|
||||
- --no-cache, -f bool: NoCache causes the execution to avoid relying on the cached artifacts resulting from a
|
||||
previous execution.
|
||||
- --replace-module string \[\*\]: ReplaceModule replaces imported go modules with local or other versions of the
|
||||
given modules. The format of the items is: \<module-path\>=\<replacement-module-path\>, like for the go mod edit
|
||||
-replace command.
|
||||
- --help: Show help.
|
||||
|
||||
### wand version
|
||||
|
||||
Show version.
|
||||
|
||||
## Environment variables:
|
||||
|
||||
Every command line option's value can also be provided as an environment variable. Environment variable names
|
||||
need to use snake casing like myapp\_foo\_bar\_baz or MYAPP\_FOO\_BAR\_BAZ, or other casing that doesn't include the
|
||||
'-' dash character, and they need to be prefixed with the name of the application, as in the base name of the
|
||||
command.
|
||||
|
||||
When both the environment variable and the command line option is defined, the command line option overrides the
|
||||
environment variable. Multiple values for the same environment variable can be defined by concatenating the
|
||||
values with the ':' separator character. When overriding multiple values with command line options, all the
|
||||
environment values of the same field are dropped.
|
||||
|
||||
### Example environment variable:
|
||||
|
||||
```
|
||||
WAND_DATE_STRING=42
|
||||
```
|
||||
|
||||
## Configuration:
|
||||
|
||||
Every command line option's value can also be provided as an entry in a configuration file.
|
||||
|
||||
Configuration file entries can use keys with different casings, e.g. snake case foo\_bar\_baz, or kebab case
|
||||
foo-bar-baz. The keys of the entries can use a limited set of characters: \[a-zA-Z0-9\_-\], and the first character
|
||||
needs to be one of \[a-zA-Z\_\]. Entry values can consist of any characters, except for newline, control
|
||||
characters, " (quote) and \\ (backslash), or the values can be quoted, in which case they can consist of any
|
||||
characters, spanning multiple lines, and only the " (quote) and \\ (backslash) characters need to be escaped by
|
||||
the \\ (backslash) character.
|
||||
|
||||
Configuration files allow multiple entries with the same key, when if the associated command line option also
|
||||
allows multiple instances (marked with \[\*\]). When an entry is defined multiple configuration files, the
|
||||
effective value is overridden in the order of the definition of the possible config files (see the listing order
|
||||
below). To discard values defined in the overridden config files without defining new ones, we can set entries
|
||||
with only the key, omitting the = key/value separator. Entries in the config files are overridden by the
|
||||
environment variables, when defined, and by the command line options when defined.
|
||||
|
||||
Config files marked as optional don't need to be present in the file system, but if they exist, then they must
|
||||
contain valid configuration syntax which is wand's flavor of .ini files
|
||||
(https://code.squareroundforest.org/arpio/wand/src/branch/main/ini.treerack).
|
||||
|
||||
### Configuration files:
|
||||
|
||||
- /etc/wand/config (optional)
|
||||
- /Users/arpio/.wand/config (optional)
|
||||
- /Users/arpio/.config/wand/config (optional)
|
||||
|
||||
### Example configuration entry:
|
||||
|
||||
```
|
||||
# Default value for --date-string:
|
||||
date_string = 42
|
||||
```
|
||||
|
||||
### Example for discarding an inherited entry:
|
||||
|
||||
```
|
||||
# Discarding an inherited entry:
|
||||
date_string
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user