cmd: reformat and expand command docs

cmd/clean.go

@@ -152,36 +152,30 @@ func getMatches(s []string, expr string, regex bool) ([]string, error) {
 
 func NewCleanCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "clean",
-		Short: "clean files and folders",
-		Long: `
-glob examples:
-bbi clean *.mod // anything with extension .mod
-bbi clean *.mod --noFolders // anything with extension .mod
-bbi clean run* // anything starting with run
-regular expression examples:
-
-bbi clean ^run --regex // anything beginning with the letters run
-bbi clean ^run -v --regex // print out files and folders that will be deleted
-bbi clean ^run --filesOnly --regex // only remove matching files
-bbi clean _est_ --dirsOnly --regex // only remove matching folders
-bbi clean _est_ --dirsOnly --preview --regex // show what output would be if clean occured but don't actually clean
-bbi clean "run009.[^mod]" --regex // all matching run009.<ext> but not .mod files
-bbi clean "run009.(mod|lst)$" --regex // match run009.lst and run009.mod
-
-can also clean via the opposite of a match with inverse
-
-bbi clean ".modt{0,1}$" --filesOnly --inverse --regex // clean all files not matching .mod or .modt
-
-clean copied files via
-
-bbi clean --copiedRuns="run001"
-bbi clean --copiedRuns="run[001:010]"
-
-can be a comma separated list as well
-
-bbi clean --copiedRuns="run[001:010],run100"
- `,
+		Use:   "clean [flags] <pattern> [<pattern>...]",
+		Short: "Clean files and folders",
+		Long: `Clean the files and directories that match the specified patterns.
+Whether the pattern is interpreted as a glob or regex is controlled by the
+--regex flag.
+
+If files were copied to the parent directory automatically after model
+execution (via the copy_lvl configuration), the original files in the run
+directory can be cleaned up by selecting the run with the --copiedRuns
+option.`,
+		Example: `  # Remove items in the current directory that end with ".mod"
+  bbi nonmem clean *.mod
+  # The same as above but ensure only files are removed
+  bbi nonmem clean --filesOnly *.mod
+
+  # Remove files in the current directory that start with "run" and end with
+  # ".mod" or ".lst"
+  bbi nonmem clean --filesOnly --regex "run.*\.(mod|lst)$"
+  # Report what the above would remove but don't actually do it
+  bbi nonmem clean --preview --filesOnly --regex "run.*\.(mod|lst)$"
+
+  # Remove copied files (recorded in '{run}_copied.json' by 'bbi run') for
+  # run001, run002, run003, and run100
+  bbi nonmem clean --copiedRuns='run[001:003],run100'`,
 		RunE: clean,
 	}
 

cmd/covcor.go

@@ -24,10 +24,10 @@ import (
 	"github.com/spf13/viper"
 )
 
-const covcorLongDescription string = `load .cov and .cor output from model(s), for example: 
-bbi nonmem covcor run001/run001
-bbi nonmem covcor run001/run001.cov
- `
+const covcorExamples string = `  # Display .cov/cor values from run001/run001.{cov,cor}
+  bbi nonmem covcor run001/run001
+  # Display the same values by specifying a full output file
+  bbi nonmem covcor run001/run001.cov`
 
 func covcor(cmd *cobra.Command, args []string) {
 	if debug {
@@ -47,9 +47,13 @@ func covcor(cmd *cobra.Command, args []string) {
 
 func NewCovcorCmd() *cobra.Command {
 	return &cobra.Command{
-		Use:   "covcor",
-		Short: "load .cov and .cor output from a model run",
-		Long:  covcorLongDescription,
-		Run:   covcor,
+		Use:   "covcor [flags] <run file>",
+		Short: "Display .cov and .cor output for a model",
+		Long: `Read the .cov and .cor files from a model's output directory and
+display the values as a JSON object. The argument is typically a shared prefix
+for the run output files, but it can be any path from which the run name can be
+derived.`,
+		Example: covcorExamples,
+		Run:     covcor,
 	}
 }

cmd/init.go

@@ -55,8 +55,13 @@ func NewInitCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Create configuration file with defaults",
-		Long: `Run bbi init to create a bbi.yaml configuration file in the current directory.
- `,
+		Long: `Write a bbi.yaml configuration file in the current directory
+to initialize it for running bbi.
+
+If the --dir=DIR option is specified, DIR should point to a directory that
+contains one or more NONMEM installations directories. Any subdirectory in
+DIR is taken as an installation if it has the expected layout (e.g., a "run"
+directory with an nmfe executable)`,
 		RunE: initializer,
 	}
 

cmd/local.go

@@ -347,10 +347,10 @@ func (l LocalModel) Cleanup(channels *turnstile.ChannelMap) {
 
 func NewLocalCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "local",
-		Short: "local specifies to run a (set of) models locally",
-		Long:  runLongDescription,
-		Run:   local,
+		Use:     "local [flags] <model> [<model>...]",
+		Short:   "Run models locally",
+		Example: fmt.Sprintf(runExamples, "local"),
+		Run:     local,
 	}
 
 	childDirIdentifier := "create_child_dirs"

cmd/nonmem.go

@@ -164,18 +164,20 @@ type NonMemModel struct {
 	Error error `json:"error"`
 }
 
-var nonmemLongDescription string = fmt.Sprintf("\n%s\n\n%s\n\n%s\n", runLongDescription, summaryLongDescription, covcorLongDescription)
+var nonmemExamples string = fmt.Sprintf("%s\n\n%s\n\n%s\n",
+	fmt.Sprintf(runExamples, "(local|sge)"),
+	summaryExamples,
+	covcorExamples)
 
 func nonmem(_ *cobra.Command, _ []string) {
-	println(nonmemLongDescription)
+	println(nonmemExamples)
 }
 
 func NewNonmemCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "nonmem",
-		Short: "nonmem a (set of) models locally or on the grid",
-		Long:  nonmemLongDescription,
-		Run:   nonmem,
+		Use:     "nonmem",
+		Short:   "Entry point for NONMEM-related subcommands",
+		Example: nonmemExamples,
 	}
 
 	// NM Selector

cmd/params.go

@@ -31,11 +31,12 @@ import (
 	"github.com/spf13/viper"
 )
 
-const paramsLongDescription string = `summarize model(s), for example:
-bbi nonmem params run001
-bbi nonmem params run001
-bbi nonmem params run001
- `
+const paramsExamples string = `  # Display table of parameters for run001
+  bbi nonmem params run001
+  # Display table of parameters for all model runs the current directory
+  bbi nonmem params --dir=.
+  # Print JSON output instead of a table
+  bbi nonmem params --json --dir=.`
 
 var (
 	noParamNames bool
@@ -416,10 +417,14 @@ func params(cmd *cobra.Command, args []string) {
 
 func NewParamsCmd() *cobra.Command {
 	var cmd = &cobra.Command{
-		Use:   "params",
-		Short: "get the parameters of model(s)",
-		Long:  paramsLongDescription,
-		Run:   params,
+		Use:   "params [flags] [<run dir>]",
+		Short: "Extract the parameter estimates of models",
+		Long: `Display the parameter values from completed models. If a directory is
+specified via --dir, get the parameters of all model runs found in that
+directory. Otherwise the positional argument should specify a run directory
+to extract parameters from.`,
+		Example: paramsExamples,
+		Run:     params,
 	}
 
 	//Used for Summary

cmd/project.go

@@ -85,11 +85,20 @@ func probs(_ *cobra.Command, args []string) error {
 }
 func NewProbsCmd() *cobra.Command {
 	return &cobra.Command{
-		Use:   "probs",
-		Short: "summarize information about project",
-		Long: `get information about models in the project:
-nmu project
- `,
+		Use:   "probs [flags] [<directory>]",
+		Short: "Summarize model definitions in a directory",
+		Long: `This subcommand extracts information from the *.mod files in the
+current directory or the specified directory. By default, it displays a
+table with the $PROBLEM text for each model file. If --json is passed, it
+prints JSON output with more details about each model (e.g., which
+estimation methods are present).
+
+Note: Only model files with a *.mod extension are currently supported.`,
+		Example: `# Output a table summarizing the $PROBLEM text for the *.mod files
+# in the current directory
+bbi nonmem probs
+# Instead of the table, show JSON output with more details
+bbi nonmem probs --json`,
 		RunE: probs,
 	}
 }

cmd/reclean.go

@@ -43,11 +43,12 @@ func reclean(cmd *cobra.Command, args []string) error {
 
 func NewRecleanCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "reclean [flags] <directory>",
-		Short: "clean files in an estimation directory by clean level",
-		Long: `
-	bbi reclean run001_est_01
- `,
+		Use:   "reclean [flags] <run dir>",
+		Short: "Clean files in run directory by specified level",
+		Example: `  bbi nonmem run local --clean_lvl=0 001.ctl
+  # Reclean the run directory for 001, deleting what would have been cleaned if
+  # the model was executed with a clean level of 1
+  bbi nonmem reclean --recleanLvl=1 001`,
 		RunE: reclean,
 	}
 

cmd/root.go

@@ -67,7 +67,7 @@ func Execute(build string) {
 func NewRootCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "bbi",
-		Short: "manage and execute models",
+		Short: "Manage and execute models",
 		Long:  fmt.Sprintf("bbi CLI version %s", VERSION),
 	}
 

cmd/run.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"bytes"
 	"errors"
+	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -17,12 +18,12 @@ import (
 	"github.com/spf13/viper"
 )
 
-const runLongDescription string = `run nonmem model(s), for example: 
-bbi nonmem run <local|sge> run001.mod
-bbi nonmem run  --clean_lvl=1 <local|sge> run001.mod run002.mod
-bbi nonmem run <local|sge> run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local
-bbi nonmem run <local|sge> .// run all models in directory
- `
+const runExamples string = `  # Execute model run001
+  bbi nonmem run %[1]s run001.mod
+  #  Run models run001.mod, run002.mod, and run003.mod
+  bbi nonmem run %[1]s 'run[001:003].mod'
+  # Run all models in the current directory
+  bbi nonmem run %[1]s .`
 
 const postProcessingScriptTemplate string = `#!/bin/bash
 
@@ -54,15 +55,16 @@ const postProcessingScriptTemplate string = `#!/bin/bash
 `
 
 func run(_ *cobra.Command, _ []string) {
-	println(runLongDescription)
+	println(fmt.Sprintf(runExamples, "(local|sge)"))
 }
 
 func NewRunCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run",
-		Short: "run a (set of) models locally or on the grid",
-		Long:  runLongDescription,
-		Run:   run,
+		Short: "Run models locally or on the grid",
+		Long: `This is the entry point to subcommands for running NONMEM models. Each
+subcommand represents a different "mode" of execution (e.g., local).`,
+		Example: fmt.Sprintf(runExamples, "(local|sge)"),
 	}
 
 	// String Variables

cmd/scaffold.go

@@ -72,12 +72,10 @@ func scaffold(cmd *cobra.Command, args []string) error {
 func NewScaffoldCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "scaffold",
-		Short: "scaffold directory structures",
-		Long: `
-	nmu scaffold --cacheDir=nmcache
-
-	nmu scaffold --cacheDir=../nmcache --preview // show where the cache dir would be created
- `,
+		Short: "Scaffold directory structures",
+		Long: `This subcommand writes a .gitignore file to the directory specified by
+--cacheDir that tells Git to ignore all files in the directory except for the
+.gitignore file itself.`,
 		RunE: scaffold,
 	}
 

cmd/sge.go

@@ -163,10 +163,10 @@ func errpanic(err error) {
 
 func NewSgeCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "sge",
-		Short: "sge specifies to run a (set of) models on the Sun Grid Engine",
-		Long:  runLongDescription,
-		Run:   sge,
+		Use:     "sge [flags] <model> [<model>...]",
+		Short:   "Run models on the Sun Grid Engine",
+		Example: fmt.Sprintf(runExamples, "sge"),
+		Run:     sge,
 	}
 
 	//String Variables

cmd/summary.go

@@ -37,12 +37,12 @@ var (
 	extFile string
 )
 
-const summaryLongDescription string = `summarize model(s), for example:
-bbi nonmem summary run001/run001
-bbi nonmem summary run001/run001.lst
-bbi nonmem summary run001/run001.res
-bbi nonmem summary run001/run001 run002/run002
- `
+const summaryExamples string = `  # Summarize run001
+  bbi nonmem summary run001/run001.lst
+  # The extension may be omitted
+  bbi nonmem summary run001/run001
+  # Output JSON summary for run001 and run002
+  bbi nonmem summary --json run001/run001 run002/run002`
 
 type jsonResults struct {
 	Results []parser.SummaryOutput
@@ -174,10 +174,17 @@ func summary(_ *cobra.Command, args []string) {
 
 func NewSummaryCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "summary",
-		Short: "summarize the output of model(s)",
-		Long:  summaryLongDescription,
-		Run:   summary,
+		Use:   "summary [flags] <lst> [<lst>...]",
+		Short: "Summarize model results",
+		Long: `Summarize the results of the specified *.lst files. By default, this
+prints a table of parameter estimates preceded by a lines with details about
+the run. Pass the --json flag to get a machine-readable output that includes
+more details.
+
+The path may also be specified without the trailing ".lst". *.res files are
+also supported.`,
+		Example: summaryExamples,
+		Run:     summary,
 	}
 
 	// Used for Summary

cmd/version.go

@@ -24,11 +24,8 @@ import (
 func NewVersionCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "version",
-		Short: "check version",
-		Long: `check the current bbi version
-bbi version
- `,
-		Run: version,
+		Short: "Print bbi's version and exit",
+		Run:   version,
 	}
 }
 

docs/commands/bbi.md

@@ -1,6 +1,6 @@
 ## bbi
 
-manage and execute models
+Manage and execute models
 
 ### Options
 
@@ -17,6 +17,6 @@ manage and execute models
 ### SEE ALSO
 
 * [bbi init](bbi_init.md)	 - Create configuration file with defaults
-* [bbi nonmem](bbi_nonmem.md)	 - nonmem a (set of) models locally or on the grid
-* [bbi version](bbi_version.md)	 - check version
+* [bbi nonmem](bbi_nonmem.md)	 - Entry point for NONMEM-related subcommands
+* [bbi version](bbi_version.md)	 - Print bbi's version and exit