Merge pull request #76 from warptools/cli-redecorating

cli redecorating

app/_docs/warpforge-catalog.md

@@ -0,0 +1,69 @@
+---
+title: "wf CLI ref: warpforge catalog"
+layout: base.njk
+eleventyNavigation:
+ parent: Warpforge CLI
+ order: 40
+---
+
+
+`warpforge catalog` command reference
+=====================================
+
+[testmark]:# (docs)
+```clidoc
+## NAME
+warpforge catalog - Subcommands that operate on catalogs
+
+## USAGE
+warpforge catalog command [command options] [arguments...]
+
+## COMMANDS
+### init
+Creates a named catalog in the root workspace
+
+### add
+Add an item to the given catalog in the root workspace. Will create a catalog if required.
+
+### release
+Add a module to the root workspace catalog as a new release
+
+### ls
+List available catalogs in the root workspace
+
+### show
+Show the contents of a module in the root workspace catalog
+
+### bundle
+Bundle required catalog items into the local workspace.
+
+### update
+Update remote catalogs in the root workspace. Will install the default warpsys catalog.
+
+### ingest-git-tags
+Ingest all tags from a git repository into a root workspace catalog entry
+
+### generate-html
+Generates HTML output for the root workspace catalog containing information on modules
+
+### mirror
+Mirror the contents of a catalog to remote warehouses
+
+### help, h
+Shows a list of commands or help for one command
+
+## OPTIONS
+#### --name=<VALUE>, -n=<VALUE>
+Name of the catalog to operate on
+
+(default: **"default"**)
+
+#### --force, -f
+Force operation, even if it causes data to be overwritten.
+
+(default: **false**)
+
+#### --help, -h
+show help
+
+```

app/_docs/warpforge.md

@@ -0,0 +1,97 @@
+---
+title: "wf CLI ref: warpforge"
+layout: base.njk
+eleventyNavigation:
+ parent: Warpforge CLI
+ order: 40
+---
+
+
+`warpforge` command reference
+=============================
+
+[testmark]:# (docs)
+```clidoc
+## NAME
+warpforge - the everything-builder and any-environment manager
+
+## USAGE
+See subcommands for details.
+
+## VERSION
+v0.4.0
+
+## COMMANDS
+### catalog
+Subcommands that operate on catalogs
+
+### check
+Check file(s) for syntax and sanity
+
+### ferk
+Starts a containerized environment for interactive use
+
+### healthcheck
+Check for potential errors in system configuration
+
+### plan
+Runs planning commands to generate inputs
+
+### quickstart
+Generate a basic module and plot
+
+### run
+Run a module or formula
+
+### spark
+Experimental RPC for getting module build status from the watch server
+
+### status, info
+Get status of workspaces and installation
+
+### ware
+Subcommands that operate on wares
+
+### watch
+Watch a module for changes to plot ingest inputs. Currently only git ingests are supported.
+
+### help, h
+Shows a list of commands or help for one command
+
+## GLOBAL OPTIONS
+#### --verbose, -v
+(default: **false**)
+
+(env var: $**WARPFORGE_DEBUG**)
+
+#### --quiet
+(default: **false**)
+
+#### --json
+Enable JSON API output
+
+(default: **false**)
+
+#### --trace.file=<VALUE>
+Enable tracing and emit output to file
+
+#### --trace.http.enable
+Enable remote tracing over http
+
+(default: **false**)
+
+#### --trace.http.insecure
+Allows insecure http
+
+(default: **false**)
+
+#### --trace.http.endpoint=<VALUE>
+Sets an endpoint for remote open-telemetry tracing collection
+
+#### --help, -h
+show help
+
+#### --version
+print the version
+
+```

app/app.go

@@ -16,3 +16,7 @@ import (
 )
 
 var App = appbase.App
+
+func init() {
+ App.Setup()
+}

app/base/appbase.go

@@ -6,14 +6,17 @@ import (
  "io"
 
  "github.com/urfave/cli/v2"
+
+ _ "github.com/warptools/warpforge/app/base/helpgen"
 )
 
 const VERSION = "v0.4.0"
 
 var App = &cli.App{
- Name: "warpforge",
- Version: VERSION,
- Usage: "the everything-builder and any-environment manager",
+ Name: "warpforge",
+ Version: VERSION,
+ Usage: "the everything-builder and any-environment manager",
+ UsageText: "See subcommands for details.",
 
  Reader: closedReader{}, // Replace with os.Stdin in real application; or other wiring, in tests.
  Writer: panicWriter{}, // Replace with os.Stdout in real application; or other wiring, in tests.
@@ -84,7 +87,9 @@ var App = &cli.App{
 // Aaaand the other modifications to `urfave/cli` that are unfortunately only possible by manipulating globals:
 func init() {
  cli.VersionFlag = &cli.BoolFlag{
- Name: "version", // And no short aliases. "-v" is for "verbose"!
+ Name: "version", // And no short aliases. "-v" is for "verbose"!
+ Usage: "print the version",
+ DisableDefaultText: true,
  }
 }
 

app/base/helpgen/helpgen.go

@@ -0,0 +1,97 @@
+/*
+This package contains our custom help text generators,
+and wires them into `urfave/cli` at package init time.
+
+We use templates which emit markdown.
+Optionally, this can be subsequently post-processed to be
+converted to nicer terminal rendering using ANSI codes --
+this feature is in another package, so you can disable it.
+
+(The use of package init time is unfortunate,
+but package sideeffects cannot be avoided:
+package-scope vars are the only option for customizing help processing
+that the `urfave/cli` package currently makes available.)
+*/
+package helpgen
+
+import (
+ "bytes"
+ "io"
+ "strings"
+ "text/tabwriter"
+ "text/template"
+
+ "github.com/urfave/cli/v2"
+ "github.com/warptools/warpforge/app/base/render"
+)
+
+/*
+ A guide to how to use the various docs strings in a cli.Command in our system:
+
+ - Usage -- this should be a one-liner, used to describe this command in the parent command's overview of its children.
+ - UsageText -- this should contain a synopsys, with examples of how to use the command and its flags. May be multi-line.
+ - Description -- freetext prose; may be multi-line. Shows up in the `-h` for that command.
+ - ArgsUsage -- UNUSED. (TODO:CONSIDER: maybe use this for synopsys, and repurpose UsageText for bighelp? Or otherwise shuffle the deck chairs.)
+
+ And outside of this:
+
+ - longer helptext for the `{appname} help {subcommandname}` feature -- that isn't actually a feature we've implemented yet.
+ If it comes, it might be based on munging the Description field. (e.g., peeking for "---" or similar, on the assumption that isn't actually needed in real content.)
+
+ For documenting cli.Flag:
+
+ - there's really only the Usage fields, per type.
+ - Short and long isn't disambiguated here either.
+ (As with commands, if we introduce this, it might be possibly to do it by munging format cues in-band.)
+*/
+
+// printHelpCustom is the entrypoint for `urfave/cli`'s customization.
+//
+// See the function of the same name upstream for reference.
+// This function is considerably derived from it.
+func printHelpCustom(out io.Writer, tmpl string, data interface{}, customFuncs map[string]interface{}) {
+
+ const hardwrap = 10000
+
+ funcMap := template.FuncMap{
+ "join": strings.Join,
+ "subtract": subtract,
+ "indent": indent,
+ "nindent": nindent,
+ "trim": strings.TrimSpace,
+ "wrap": func(input string, offset int) string { return wrap(input, offset, hardwrap) },
+ "offset": offset,
+ "offsetCommands": offsetCommands,
+ }
+ for key, value := range customFuncs {
+ funcMap[key] = value
+ }
+
+ var buf bytes.Buffer
+ w := tabwriter.NewWriter(&buf, 1, 8, 4, ' ', 0)
+ t := template.Must(template.New("help").Funcs(funcMap).Parse(tmpl))
+ template.Must(t.New("helpNameTemplate").Parse(helpNameTemplate))
+ template.Must(t.New("usageTemplate").Parse(usageTemplate))
+ template.Must(t.New("visibleCommandTemplate").Parse(visibleCommandTemplate))
+ template.Must(t.New("visibleFlagCategoryTemplate").Parse(visibleFlagCategoryTemplate))
+ template.Must(t.New("visibleFlagTemplate").Parse(visibleFlagTemplate))
+ template.Must(t.New("visibleGlobalFlagCategoryTemplate").Parse(strings.Replace(visibleFlagCategoryTemplate, "OPTIONS", "GLOBAL OPTIONS", -1)))
+ template.Must(t.New("authorsTemplate").Parse(authorsTemplate))
+ template.Must(t.New("visibleCommandCategoryTemplate").Parse(visibleCommandCategoryTemplate))
+
+ err := t.Execute(w, data)
+ if err != nil {
+ panic(err)
+ }
+ _ = w.Flush()
+
+ if err := render.Render(buf.Bytes(), out, Mode); err != nil {
+ panic(err)
+ }
+}
+
+var Mode = render.Mode_ANSIdown
+
+func init() {
+ cli.HelpPrinterCustom = printHelpCustom
+}