diff --git a/.github/workflows/site.yaml b/.github/workflows/site.yaml new file mode 100644 index 00000000..ca519739 --- /dev/null +++ b/.github/workflows/site.yaml @@ -0,0 +1,67 @@ +name: Deploy site +on: + push: + branches: + - scratch/deploy-site + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Install Hugo + shell: bash + run: | + tdir=$(mktemp -d) + tgz=$tdir/hugo.tar.gz + bin=$HOME/bin + mkdir -p "$bin" + + url=https://github.com/gohugoio/hugo/releases/download + curl -fSsL --retry 3 \ + "$url/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" \ + >"$tgz" + printf '%s %s\n' "$HUGO_SHA" "$tgz" | sha256sum --check >/dev/null + + tar --to-stdout --extract -zf "$tgz" hugo >"$bin"/hugo + chmod +x "$bin/hugo" + "$bin"/hugo version + echo "$bin" >>"$GITHUB_PATH" + env: + HUGO_VERSION: '0.133.0' + HUGO_SHA: '372530e2de9ae74087a987ca841429390a055123b8a4dec665cc601f10dc8e6e' + - uses: actions/configure-pages@v5 + id: pages + - name: Check URL match + shell: bash + run: | + url=$(grep '^baseURL:' docs/site/hugo.yaml) + test "${{ steps.pages.outputs.base_url }}/" = "${url#baseURL: }" + - name: Build site + shell: bash + run: make -C docs/site build + env: + HUGO_ENVIRONMENT: production + HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache + TZ: America/New_York + - name: Upload site + uses: actions/upload-pages-artifact@v3 + with: + path: ./docs/site/public + deploy: + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index d6294020..d9faedf4 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ # bbi +Documentation for `bbi` is available at +. + bbi is (will be) a complete solution for managing projects involving modeling and simulation with a number of software solutions used in pharmaceutical sciences. @@ -316,15 +319,21 @@ No Heuristic Problems Detected ### Development -Test-driven development encouraged, facilitated by goconvey to monitor coverage -and re-run tests on change(s) +To run the test suite, you can invoke [scripts/run-unit-tests][ru] and +[scripts/run-integration-tests][ri] directly or via `make vt-test`. -During development, while installing new versions for testing, running "make install" will auto-append a timestamp to the build version. +After updating a subcommand, regenerate the Markdown documentation at +[docs/commands][dc] by running `make vt-gen-docs`. See `make vt-help` and +[internal/valtools/README.md][vr] for more details on the validation tooling. -``` -$ go get github.com/smartystreets/goconvey -goconvey -``` +The setup for building the documentation site is described in +[docs/site/README.md][dr]. -a web UI will be started at localhost:8080 with file watchers to rerun tests on -file change(s) + + + +[dc]: https://github.com/metrumresearchgroup/bbi/blob/main/docs/commands +[dr]: https://github.com/metrumresearchgroup/bbi/blob/main/docs/site/README.md +[ri]: https://github.com/metrumresearchgroup/bbi/blob/main/scripts/run-integration-tests +[ru]: https://github.com/metrumresearchgroup/bbi/blob/main/scripts/run-unit-tests +[vr]: https://github.com/metrumresearchgroup/bbi/blob/main/internal/valtools/README.md diff --git a/cmd/clean.go b/cmd/clean.go index 68ae963a..ff32ea68 100644 --- a/cmd/clean.go +++ b/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. 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] [...]", + 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, } diff --git a/cmd/covcor.go b/cmd/covcor.go index 3dfa3d58..26a9e40c 100644 --- a/cmd/covcor.go +++ b/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] ", + 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, } } diff --git a/cmd/init.go b/cmd/init.go index 11f57ae1..0df7b28c 100644 --- a/cmd/init.go +++ b/cmd/init.go @@ -55,13 +55,18 @@ 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, } const directory string = "dir" - cmd.Flags().StringSlice(directory, []string{}, "A directory in which to look for NonMem Installations") + cmd.Flags().StringSlice(directory, []string{}, "directory in which to look for NONMEM installations") return cmd } diff --git a/cmd/local.go b/cmd/local.go index be0d5f5a..851bac2d 100644 --- a/cmd/local.go +++ b/cmd/local.go @@ -347,15 +347,15 @@ 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] [...]", + Short: "Run models locally", + Example: fmt.Sprintf(runExamples, "local"), + Run: local, } childDirIdentifier := "create_child_dirs" - cmd.PersistentFlags().Bool(childDirIdentifier, true, "Indicates whether or not local branch execution"+ - "should create a new subdirectory with the output_dir variable as its name and execute in that directory") + cmd.PersistentFlags().Bool(childDirIdentifier, true, + "create a new subdirectory, named based on the output_dir option, for execution") errpanic(viper.BindPFlag("local."+childDirIdentifier, cmd.PersistentFlags().Lookup(childDirIdentifier))) return cmd diff --git a/cmd/nonmem.go b/cmd/nonmem.go index 8d1ed1ff..aa58c03d 100644 --- a/cmd/nonmem.go +++ b/cmd/nonmem.go @@ -164,79 +164,82 @@ 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, + Run: nonmem, } // NM Selector const nmVersionIdentifier string = "nm_version" - cmd.PersistentFlags().String(nmVersionIdentifier, "", "Version of nonmem from the configuration list to use") + cmd.PersistentFlags().String(nmVersionIdentifier, "", "version of NONMEM from the configuration list to use") errpanic(viper.BindPFlag(nmVersionIdentifier, cmd.PersistentFlags().Lookup(nmVersionIdentifier))) // Parallelization Components const parallelIdentifier string = "parallel" - cmd.PersistentFlags().Bool(parallelIdentifier, false, "Whether or not to run nonmem in parallel mode") + cmd.PersistentFlags().Bool(parallelIdentifier, false, "whether to run NONMEM in parallel mode") errpanic(viper.BindPFlag(parallelIdentifier, cmd.PersistentFlags().Lookup(parallelIdentifier))) const parallelCompletionTimeoutIdentifier string = "parallel_timeout" - cmd.PersistentFlags().Int(parallelCompletionTimeoutIdentifier, 2147483647, "The amount of time to wait for parallel operations in nonmem before timing out") + cmd.PersistentFlags().Int(parallelCompletionTimeoutIdentifier, 2147483647, "amount of time to wait for parallel operations in NONMEM before timing out") errpanic(viper.BindPFlag(parallelCompletionTimeoutIdentifier, cmd.PersistentFlags().Lookup(parallelCompletionTimeoutIdentifier))) const mpiExecPathIdentifier string = "mpi_exec_path" - cmd.PersistentFlags().String(mpiExecPathIdentifier, "/usr/local/mpich3/bin/mpiexec", "The fully qualified path to mpiexec. Used for nonmem parallel operations") + cmd.PersistentFlags().String(mpiExecPathIdentifier, "/usr/local/mpich3/bin/mpiexec", "fully qualified path to mpiexec to use for NONMEM parallel operations") errpanic(viper.BindPFlag(mpiExecPathIdentifier, cmd.PersistentFlags().Lookup(mpiExecPathIdentifier))) const parafileIdentifier string = "parafile" - cmd.PersistentFlags().String(parafileIdentifier, "", "Location of a user-provided parafile to use for parallel execution") + cmd.PersistentFlags().String(parafileIdentifier, "", "location of a user-provided parafile to use for parallel execution") errpanic(viper.BindPFlag(parafileIdentifier, cmd.PersistentFlags().Lookup(parafileIdentifier))) const nmQualIdentifier string = "nmqual" - cmd.PersistentFlags().Bool(nmQualIdentifier, false, "Whether or not to execute with nmqual (autolog.pl)") + cmd.PersistentFlags().Bool(nmQualIdentifier, false, "whether to execute with nmqual (autolog.pl)") errpanic(viper.BindPFlag(nmQualIdentifier, cmd.PersistentFlags().Lookup(nmQualIdentifier))) // NMFE Options const nmfeGroup string = "nmfe_options" const licFileIdentifier string = "licfile" - cmd.PersistentFlags().String(licFileIdentifier, "", "RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem)") + cmd.PersistentFlags().String(licFileIdentifier, "", "RAW NMFE OPTION - NONMEM license file to use") errpanic(viper.BindPFlag(nmfeGroup+"."+licFileIdentifier, cmd.PersistentFlags().Lookup(licFileIdentifier))) const prSameIdentifier string = "prsame" - cmd.PersistentFlags().Bool(prSameIdentifier, false, "RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped") + cmd.PersistentFlags().Bool(prSameIdentifier, false, "RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step") errpanic(viper.BindPFlag(nmfeGroup+"."+prSameIdentifier, cmd.PersistentFlags().Lookup(prSameIdentifier))) const backgroundIdentifier string = "background" - cmd.PersistentFlags().Bool(backgroundIdentifier, false, "RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters") + cmd.PersistentFlags().Bool(backgroundIdentifier, false, "RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters") errpanic(viper.BindPFlag(nmfeGroup+"."+backgroundIdentifier, cmd.PersistentFlags().Lookup(backgroundIdentifier))) const prCompileIdentifier string = "prcompile" - cmd.PersistentFlags().Bool(prCompileIdentifier, false, "RAW NMFE OPTION - Forces PREDPP compilation") + cmd.PersistentFlags().Bool(prCompileIdentifier, false, "RAW NMFE OPTION - forces PREDPP compilation") errpanic(viper.BindPFlag(nmfeGroup+"."+prCompileIdentifier, cmd.PersistentFlags().Lookup(prCompileIdentifier))) const prDefaultIdentifier string = "prdefault" - cmd.PersistentFlags().Bool(prDefaultIdentifier, false, "RAW NMFE OPTION - Do not recompile any routines other than FSUBS") + cmd.PersistentFlags().Bool(prDefaultIdentifier, false, "RAW NMFE OPTION - do not recompile any routines other than FSUBS") errpanic(viper.BindPFlag(nmfeGroup+"."+prDefaultIdentifier, cmd.PersistentFlags().Lookup(prDefaultIdentifier))) const tprDefaultIdentifier string = "tprdefault" - cmd.PersistentFlags().Bool(tprDefaultIdentifier, false, "RAW NMFE OPTION - Test if is okay to do -prdefault") + cmd.PersistentFlags().Bool(tprDefaultIdentifier, false, "RAW NMFE OPTION - test if is okay to do -prdefault") errpanic(viper.BindPFlag(nmfeGroup+"."+tprDefaultIdentifier, cmd.PersistentFlags().Lookup(tprDefaultIdentifier))) const noBuildIdentifier string = "nobuild" - cmd.PersistentFlags().Bool(noBuildIdentifier, false, "RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable") + cmd.PersistentFlags().Bool(noBuildIdentifier, false, "RAW NMFE OPTION - do not build a new NONMEM executable") errpanic(viper.BindPFlag(nmfeGroup+"."+noBuildIdentifier, cmd.PersistentFlags().Lookup(noBuildIdentifier))) const maxLimIdentifier string = "maxlim" cmd.PersistentFlags().Int(maxLimIdentifier, 2, - "RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe)") + "RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe)") errpanic(viper.BindPFlag(nmfeGroup+"."+maxLimIdentifier, cmd.PersistentFlags().Lookup(maxLimIdentifier))) cmd.AddCommand(NewCleanCmd()) diff --git a/cmd/params.go b/cmd/params.go index 6c43ee68..76bd7b89 100644 --- a/cmd/params.go +++ b/cmd/params.go @@ -32,11 +32,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 @@ -434,10 +435,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] []", + 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 diff --git a/cmd/project.go b/cmd/project.go index 30740817..fbbccb92 100644 --- a/cmd/project.go +++ b/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] []", + 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, } } diff --git a/cmd/reclean.go b/cmd/reclean.go index c7521fe4..bf8821ad 100644 --- a/cmd/reclean.go +++ b/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] ", - Short: "clean files in an estimation directory by clean level", - Long: ` - bbi reclean run001_est_01 - `, + Use: "reclean [flags] ", + 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, } diff --git a/cmd/root.go b/cmd/root.go index 2127cfbb..fa8036e6 100644 --- a/cmd/root.go +++ b/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), } @@ -92,7 +92,7 @@ func NewRootCmd() *cobra.Command { cmd.PersistentFlags().IntVar(&threads, "threads", 4, "number of threads to execute with locally or nodes to execute on in parallel") errpanic(viper.BindPFlag("threads", cmd.PersistentFlags().Lookup("threads"))) // Update to make sure viper binds to the flag - cmd.PersistentFlags().BoolVar(&Json, "json", false, "json tree of output, if possible") + cmd.PersistentFlags().BoolVar(&Json, "json", false, "show JSON output, if possible") errpanic(viper.BindPFlag("json", cmd.PersistentFlags().Lookup("json"))) // Bind to viper cmd.PersistentFlags().BoolVarP(&preview, "preview", "p", false, "preview action, but don't actually run command") diff --git a/cmd/run.go b/cmd/run.go index 70496bbd..fba72915 100644 --- a/cmd/run.go +++ b/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 run001.mod -bbi nonmem run --clean_lvl=1 run001.mod run002.mod -bbi nonmem run run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local -bbi nonmem run .// 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,17 @@ 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)"), + Run: run, } // String Variables @@ -80,12 +83,12 @@ func NewRunCmd() *cobra.Command { viper.SetDefault("output_dir", "{{ .Name }}") // Int Variables - cmd.PersistentFlags().Int("clean_lvl", 1, "clean level used for file output from a given (set of) runs") + cmd.PersistentFlags().Int("clean_lvl", 1, "clean level used for output") errpanic(viper.BindPFlag("clean_lvl", cmd.PersistentFlags().Lookup("clean_lvl"))) // TODO: these are likely not meangingful as should be set in configlib, but want to configm viper.SetDefault("clean_lvl", 1) - cmd.PersistentFlags().Int("copy_lvl", 0, "copy level used for file output from a given (set of) runs") + cmd.PersistentFlags().Int("copy_lvl", 0, "copy level used for output") errpanic(viper.BindPFlag("copy_lvl", cmd.PersistentFlags().Lookup("copy_lvl"))) viper.SetDefault("copy_lvl", 0) @@ -98,16 +101,16 @@ func NewRunCmd() *cobra.Command { errpanic(viper.BindPFlag("git", cmd.PersistentFlags().Lookup("git"))) viper.SetDefault("git", true) - cmd.PersistentFlags().Bool("overwrite", false, "Whether or not to remove existing output directories if they are present") + cmd.PersistentFlags().Bool("overwrite", false, "whether to remove existing output directories") errpanic(viper.BindPFlag("overwrite", cmd.PersistentFlags().Lookup("overwrite"))) viper.SetDefault("overwrite", false) const configIdentifier string = "config" - cmd.PersistentFlags().String(configIdentifier, "", "Path (relative or absolute) to another bbi.yaml to load") + cmd.PersistentFlags().String(configIdentifier, "", "path to another bbi.yaml to load") errpanic(viper.BindPFlag(configIdentifier, cmd.PersistentFlags().Lookup(configIdentifier))) const saveconfig string = "save_config" - cmd.PersistentFlags().Bool(saveconfig, true, "Whether or not to save the existing configuration to a file with the model") + cmd.PersistentFlags().Bool(saveconfig, true, "whether to save the existing configuration to the output directory") errpanic(viper.BindPFlag(saveconfig, cmd.PersistentFlags().Lookup(saveconfig))) const delayIdentifier string = "delay" @@ -115,15 +118,15 @@ func NewRunCmd() *cobra.Command { errpanic(viper.BindPFlag(delayIdentifier, cmd.PersistentFlags().Lookup(delayIdentifier))) const logFileIdentifier string = "log_file" - cmd.PersistentFlags().String(logFileIdentifier, "", "If populated, specifies the file into which to store the output / logging details from bbi") + cmd.PersistentFlags().String(logFileIdentifier, "", "file into which to store the output / logging details from bbi") errpanic(viper.BindPFlag(logFileIdentifier, cmd.PersistentFlags().Lookup(logFileIdentifier))) const postExecutionHookIdentifier string = "post_work_executable" - cmd.PersistentFlags().String(postExecutionHookIdentifier, "", "A script or binary to run when job execution completes or fails") + cmd.PersistentFlags().String(postExecutionHookIdentifier, "", "script or binary to run when job execution completes or fails") errpanic(viper.BindPFlag(postExecutionHookIdentifier, cmd.PersistentFlags().Lookup(postExecutionHookIdentifier))) const additionalEnvIdentifier string = "additional_post_work_envs" - cmd.PersistentFlags().StringSlice(additionalEnvIdentifier, []string{}, "Any additional values (as ENV KEY=VALUE) to provide for the post execution environment") + cmd.PersistentFlags().StringSlice(additionalEnvIdentifier, []string{}, "additional values (as ENV KEY=VALUE) to provide for the post execution environment") errpanic(viper.BindPFlag(additionalEnvIdentifier, cmd.PersistentFlags().Lookup(additionalEnvIdentifier))) cmd.AddCommand(NewLocalCmd()) diff --git a/cmd/scaffold.go b/cmd/scaffold.go index 97879c53..356e6f4b 100644 --- a/cmd/scaffold.go +++ b/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, } diff --git a/cmd/sge.go b/cmd/sge.go index 9ac1b9af..bb3a7e09 100644 --- a/cmd/sge.go +++ b/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] [...]", + Short: "Run models on the Sun Grid Engine", + Example: fmt.Sprintf(runExamples, "sge"), + Run: sge, } //String Variables diff --git a/cmd/summary.go b/cmd/summary.go index e46df2b5..68ae1c4a 100644 --- a/cmd/summary.go +++ b/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] [...]", + 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 diff --git a/cmd/version.go b/cmd/version.go index 0ae8eeb5..d6b16dc0 100644 --- a/cmd/version.go +++ b/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, } } diff --git a/docs/commands/bbi.md b/docs/commands/bbi.md index 8eb21687..dbefa6e1 100644 --- a/docs/commands/bbi.md +++ b/docs/commands/bbi.md @@ -1,13 +1,13 @@ ## bbi -manage and execute models +Manage and execute models ### Options ``` -d, --debug debug mode -h, --help help for bbi - --json json tree of output, if possible + --json show JSON output, if possible -o, --output string output file -p, --preview preview action, but don't actually run command --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) @@ -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 diff --git a/docs/commands/bbi_init.md b/docs/commands/bbi_init.md index f63f6baa..bfe79b00 100644 --- a/docs/commands/bbi_init.md +++ b/docs/commands/bbi_init.md @@ -4,8 +4,13 @@ Create configuration file with defaults ### Synopsis -Run bbi init to create a bbi.yaml configuration file in the current directory. - +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) ``` bbi init [flags] @@ -14,7 +19,7 @@ bbi init [flags] ### Options ``` - --dir strings A directory in which to look for NonMem Installations + --dir strings directory in which to look for NONMEM installations -h, --help help for init ``` @@ -22,7 +27,7 @@ bbi init [flags] ``` -d, --debug debug mode - --json json tree of output, if possible + --json show JSON output, if possible -o, --output string output file -p, --preview preview action, but don't actually run command --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) @@ -31,5 +36,5 @@ bbi init [flags] ### SEE ALSO -* [bbi](bbi.md) - manage and execute models +* [bbi](bbi.md) - Manage and execute models diff --git a/docs/commands/bbi_nonmem.md b/docs/commands/bbi_nonmem.md index 661e36ef..d958cd4b 100644 --- a/docs/commands/bbi_nonmem.md +++ b/docs/commands/bbi_nonmem.md @@ -1,59 +1,60 @@ ## bbi nonmem -nonmem a (set of) models locally or on the grid - -### Synopsis +Entry point for NONMEM-related subcommands +``` +bbi nonmem [flags] +``` -run nonmem model(s), for example: -bbi nonmem run run001.mod -bbi nonmem run --clean_lvl=1 run001.mod run002.mod -bbi nonmem run run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local -bbi nonmem run .// run all models in directory - +### Examples -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 - +``` + # Execute model run001 + bbi nonmem run (local|sge) run001.mod + # Run models run001.mod, run002.mod, and run003.mod + bbi nonmem run (local|sge) 'run[001:003].mod' + # Run all models in the current directory + bbi nonmem run (local|sge) . -load .cov and .cor output from model(s), for example: -bbi nonmem covcor run001/run001 -bbi nonmem covcor run001/run001.cov - + # 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 + # 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 -``` -bbi nonmem [flags] ``` ### Options ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -h, --help help for nonmem - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault ``` ### Options inherited from parent commands ``` -d, --debug debug mode - --json json tree of output, if possible + --json show JSON output, if possible -o, --output string output file -p, --preview preview action, but don't actually run command --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) @@ -62,13 +63,13 @@ bbi nonmem [flags] ### SEE ALSO -* [bbi](bbi.md) - manage and execute models -* [bbi nonmem clean](bbi_nonmem_clean.md) - clean files and folders -* [bbi nonmem covcor](bbi_nonmem_covcor.md) - load .cov and .cor output from a model run -* [bbi nonmem params](bbi_nonmem_params.md) - get the parameters of model(s) -* [bbi nonmem probs](bbi_nonmem_probs.md) - summarize information about project -* [bbi nonmem reclean](bbi_nonmem_reclean.md) - clean files in an estimation directory by clean level -* [bbi nonmem run](bbi_nonmem_run.md) - run a (set of) models locally or on the grid -* [bbi nonmem scaffold](bbi_nonmem_scaffold.md) - scaffold directory structures -* [bbi nonmem summary](bbi_nonmem_summary.md) - summarize the output of model(s) +* [bbi](bbi.md) - Manage and execute models +* [bbi nonmem clean](bbi_nonmem_clean.md) - Clean files and folders +* [bbi nonmem covcor](bbi_nonmem_covcor.md) - Display .cov and .cor output for a model +* [bbi nonmem params](bbi_nonmem_params.md) - Extract the parameter estimates of models +* [bbi nonmem probs](bbi_nonmem_probs.md) - Summarize model definitions in a directory +* [bbi nonmem reclean](bbi_nonmem_reclean.md) - Clean files in run directory by specified level +* [bbi nonmem run](bbi_nonmem_run.md) - Run models locally or on the grid +* [bbi nonmem scaffold](bbi_nonmem_scaffold.md) - Scaffold directory structures +* [bbi nonmem summary](bbi_nonmem_summary.md) - Summarize model results diff --git a/docs/commands/bbi_nonmem_clean.md b/docs/commands/bbi_nonmem_clean.md index 58107ae3..c7f26f5f 100644 --- a/docs/commands/bbi_nonmem_clean.md +++ b/docs/commands/bbi_nonmem_clean.md @@ -1,40 +1,39 @@ ## bbi nonmem clean -clean files and folders +Clean files and folders ### Synopsis +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. -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: +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. -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. 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 nonmem clean [flags] [...] +``` -bbi clean --copiedRuns="run[001:010],run100" - +### Examples ``` -bbi nonmem clean [flags] + # 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' ``` ### Options @@ -51,29 +50,29 @@ bbi nonmem clean [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_covcor.md b/docs/commands/bbi_nonmem_covcor.md index 3ef2d1ef..8622a578 100644 --- a/docs/commands/bbi_nonmem_covcor.md +++ b/docs/commands/bbi_nonmem_covcor.md @@ -1,16 +1,25 @@ ## bbi nonmem covcor -load .cov and .cor output from a model run +Display .cov and .cor output for a model ### Synopsis -load .cov and .cor output from model(s), for example: -bbi nonmem covcor run001/run001 -bbi nonmem covcor run001/run001.cov - +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. ``` -bbi nonmem covcor [flags] +bbi nonmem covcor [flags] +``` + +### Examples + +``` + # 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 ``` ### Options @@ -22,29 +31,29 @@ bbi nonmem covcor [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_params.md b/docs/commands/bbi_nonmem_params.md index ff6bdfcd..161a370f 100644 --- a/docs/commands/bbi_nonmem_params.md +++ b/docs/commands/bbi_nonmem_params.md @@ -1,17 +1,27 @@ ## bbi nonmem params -get the parameters of model(s) +Extract the parameter estimates of models ### Synopsis -summarize model(s), for example: -bbi nonmem params run001 -bbi nonmem params run001 -bbi nonmem params run001 - +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. ``` -bbi nonmem params [flags] +bbi nonmem params [flags] [] +``` + +### Examples + +``` + # 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=. ``` ### Options @@ -26,29 +36,29 @@ bbi nonmem params [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_probs.md b/docs/commands/bbi_nonmem_probs.md index b4735a32..4592a90a 100644 --- a/docs/commands/bbi_nonmem_probs.md +++ b/docs/commands/bbi_nonmem_probs.md @@ -1,15 +1,29 @@ ## bbi nonmem probs -summarize information about project +Summarize model definitions in a directory ### Synopsis -get information about models in the project: -nmu project - +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. + +``` +bbi nonmem probs [flags] [] +``` + +### Examples ``` -bbi nonmem probs [flags] +# 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 ``` ### Options @@ -21,29 +35,29 @@ bbi nonmem probs [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_reclean.md b/docs/commands/bbi_nonmem_reclean.md index 3069e767..b7b9915c 100644 --- a/docs/commands/bbi_nonmem_reclean.md +++ b/docs/commands/bbi_nonmem_reclean.md @@ -1,15 +1,18 @@ ## bbi nonmem reclean -clean files in an estimation directory by clean level - -### Synopsis +Clean files in run directory by specified level +``` +bbi nonmem reclean [flags] +``` - bbi reclean run001_est_01 - +### Examples ``` -bbi nonmem reclean [flags] + 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 ``` ### Options @@ -22,29 +25,29 @@ bbi nonmem reclean [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_run.md b/docs/commands/bbi_nonmem_run.md index c57cba6e..0e9730fd 100644 --- a/docs/commands/bbi_nonmem_run.md +++ b/docs/commands/bbi_nonmem_run.md @@ -1,65 +1,72 @@ ## bbi nonmem run -run a (set of) models locally or on the grid +Run models locally or on the grid ### Synopsis -run nonmem model(s), for example: -bbi nonmem run run001.mod -bbi nonmem run --clean_lvl=1 run001.mod run002.mod -bbi nonmem run run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local -bbi nonmem run .// run all models in directory - +This is the entry point to subcommands for running NONMEM models. Each +subcommand represents a different "mode" of execution (e.g., local). ``` bbi nonmem run [flags] ``` +### Examples + +``` + # Execute model run001 + bbi nonmem run (local|sge) run001.mod + # Run models run001.mod, run002.mod, and run003.mod + bbi nonmem run (local|sge) 'run[001:003].mod' + # Run all models in the current directory + bbi nonmem run (local|sge) . +``` + ### Options ``` - --additional_post_work_envs strings Any additional values (as ENV KEY=VALUE) to provide for the post execution environment - --clean_lvl int clean level used for file output from a given (set of) runs (default 1) - --config string Path (relative or absolute) to another bbi.yaml to load - --copy_lvl int copy level used for file output from a given (set of) runs + --additional_post_work_envs strings additional values (as ENV KEY=VALUE) to provide for the post execution environment + --clean_lvl int clean level used for output (default 1) + --config string path to another bbi.yaml to load + --copy_lvl int copy level used for output --delay int Selects a random number of seconds between 1 and this value to stagger / jitter job execution. Assists in dealing with large volumes of work dealing with the same data set. May avoid NMTRAN issues about not being able read / close files --git whether git is used -h, --help help for run - --log_file string If populated, specifies the file into which to store the output / logging details from bbi + --log_file string file into which to store the output / logging details from bbi --output_dir string Go template for the output directory to use for storing details of each executed model (default "{{ .Name }}") - --overwrite Whether or not to remove existing output directories if they are present - --post_work_executable string A script or binary to run when job execution completes or fails - --save_config Whether or not to save the existing configuration to a file with the model (default true) + --overwrite whether to remove existing output directories + --post_work_executable string script or binary to run when job execution completes or fails + --save_config whether to save the existing configuration to the output directory (default true) ``` ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid -* [bbi nonmem run local](bbi_nonmem_run_local.md) - local specifies to run a (set of) models locally -* [bbi nonmem run sge](bbi_nonmem_run_sge.md) - sge specifies to run a (set of) models on the Sun Grid Engine +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands +* [bbi nonmem run local](bbi_nonmem_run_local.md) - Run models locally +* [bbi nonmem run sge](bbi_nonmem_run_sge.md) - Run models on the Sun Grid Engine diff --git a/docs/commands/bbi_nonmem_run_local.md b/docs/commands/bbi_nonmem_run_local.md index 8f29a62f..db7f5e3e 100644 --- a/docs/commands/bbi_nonmem_run_local.md +++ b/docs/commands/bbi_nonmem_run_local.md @@ -1,64 +1,66 @@ ## bbi nonmem run local -local specifies to run a (set of) models locally +Run models locally -### Synopsis +``` +bbi nonmem run local [flags] [...] +``` -run nonmem model(s), for example: -bbi nonmem run run001.mod -bbi nonmem run --clean_lvl=1 run001.mod run002.mod -bbi nonmem run run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local -bbi nonmem run .// run all models in directory - +### Examples ``` -bbi nonmem run local [flags] + # Execute model run001 + bbi nonmem run local run001.mod + # Run models run001.mod, run002.mod, and run003.mod + bbi nonmem run local 'run[001:003].mod' + # Run all models in the current directory + bbi nonmem run local . ``` ### Options ``` - --create_child_dirs Indicates whether or not local branch executionshould create a new subdirectory with the output_dir variable as its name and execute in that directory (default true) + --create_child_dirs create a new subdirectory, named based on the output_dir option, for execution (default true) -h, --help help for local ``` ### Options inherited from parent commands ``` - --additional_post_work_envs strings Any additional values (as ENV KEY=VALUE) to provide for the post execution environment - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters - --clean_lvl int clean level used for file output from a given (set of) runs (default 1) - --config string Path (relative or absolute) to another bbi.yaml to load - --copy_lvl int copy level used for file output from a given (set of) runs + --additional_post_work_envs strings additional values (as ENV KEY=VALUE) to provide for the post execution environment + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters + --clean_lvl int clean level used for output (default 1) + --config string path to another bbi.yaml to load + --copy_lvl int copy level used for output -d, --debug debug mode --delay int Selects a random number of seconds between 1 and this value to stagger / jitter job execution. Assists in dealing with large volumes of work dealing with the same data set. May avoid NMTRAN issues about not being able read / close files --git whether git is used - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --log_file string If populated, specifies the file into which to store the output / logging details from bbi - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --log_file string file into which to store the output / logging details from bbi + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file --output_dir string Go template for the output directory to use for storing details of each executed model (default "{{ .Name }}") - --overwrite Whether or not to remove existing output directories if they are present - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --post_work_executable string A script or binary to run when job execution completes or fails - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --overwrite whether to remove existing output directories + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --post_work_executable string script or binary to run when job execution completes or fails + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped - --save_config Whether or not to save the existing configuration to a file with the model (default true) + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step + --save_config whether to save the existing configuration to the output directory (default true) --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem run](bbi_nonmem_run.md) - run a (set of) models locally or on the grid +* [bbi nonmem run](bbi_nonmem_run.md) - Run models locally or on the grid diff --git a/docs/commands/bbi_nonmem_run_sge.md b/docs/commands/bbi_nonmem_run_sge.md index ebc6a404..1887d47b 100644 --- a/docs/commands/bbi_nonmem_run_sge.md +++ b/docs/commands/bbi_nonmem_run_sge.md @@ -1,18 +1,20 @@ ## bbi nonmem run sge -sge specifies to run a (set of) models on the Sun Grid Engine +Run models on the Sun Grid Engine -### Synopsis +``` +bbi nonmem run sge [flags] [...] +``` -run nonmem model(s), for example: -bbi nonmem run run001.mod -bbi nonmem run --clean_lvl=1 run001.mod run002.mod -bbi nonmem run run[001:006].mod // expand to run001.mod run002.mod ... run006.mod local -bbi nonmem run .// run all models in directory - +### Examples ``` -bbi nonmem run sge [flags] + # Execute model run001 + bbi nonmem run sge run001.mod + # Run models run001.mod, run002.mod, and run003.mod + bbi nonmem run sge 'run[001:003].mod' + # Run all models in the current directory + bbi nonmem run sge . ``` ### Options @@ -26,40 +28,40 @@ bbi nonmem run sge [flags] ### Options inherited from parent commands ``` - --additional_post_work_envs strings Any additional values (as ENV KEY=VALUE) to provide for the post execution environment - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters - --clean_lvl int clean level used for file output from a given (set of) runs (default 1) - --config string Path (relative or absolute) to another bbi.yaml to load - --copy_lvl int copy level used for file output from a given (set of) runs + --additional_post_work_envs strings additional values (as ENV KEY=VALUE) to provide for the post execution environment + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters + --clean_lvl int clean level used for output (default 1) + --config string path to another bbi.yaml to load + --copy_lvl int copy level used for output -d, --debug debug mode --delay int Selects a random number of seconds between 1 and this value to stagger / jitter job execution. Assists in dealing with large volumes of work dealing with the same data set. May avoid NMTRAN issues about not being able read / close files --git whether git is used - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --log_file string If populated, specifies the file into which to store the output / logging details from bbi - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --log_file string file into which to store the output / logging details from bbi + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file --output_dir string Go template for the output directory to use for storing details of each executed model (default "{{ .Name }}") - --overwrite Whether or not to remove existing output directories if they are present - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --post_work_executable string A script or binary to run when job execution completes or fails - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --overwrite whether to remove existing output directories + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --post_work_executable string script or binary to run when job execution completes or fails + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped - --save_config Whether or not to save the existing configuration to a file with the model (default true) + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step + --save_config whether to save the existing configuration to the output directory (default true) --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem run](bbi_nonmem_run.md) - run a (set of) models locally or on the grid +* [bbi nonmem run](bbi_nonmem_run.md) - Run models locally or on the grid diff --git a/docs/commands/bbi_nonmem_scaffold.md b/docs/commands/bbi_nonmem_scaffold.md index dcabb3fa..9eb2cfb0 100644 --- a/docs/commands/bbi_nonmem_scaffold.md +++ b/docs/commands/bbi_nonmem_scaffold.md @@ -1,14 +1,12 @@ ## bbi nonmem scaffold -scaffold directory structures +Scaffold directory structures ### Synopsis - - nmu scaffold --cacheDir=nmcache - - nmu scaffold --cacheDir=../nmcache --preview // show where the cache dir would be created - +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. ``` bbi nonmem scaffold [flags] @@ -24,29 +22,29 @@ bbi nonmem scaffold [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_nonmem_summary.md b/docs/commands/bbi_nonmem_summary.md index f00cb692..c86a3c06 100644 --- a/docs/commands/bbi_nonmem_summary.md +++ b/docs/commands/bbi_nonmem_summary.md @@ -1,18 +1,30 @@ ## bbi nonmem summary -summarize the output of model(s) +Summarize model results ### Synopsis -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 - +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. + +``` +bbi nonmem summary [flags] [...] +``` + +### Examples ``` -bbi nonmem summary [flags] + # 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 ``` ### Options @@ -28,29 +40,29 @@ bbi nonmem summary [flags] ### Options inherited from parent commands ``` - --background RAW NMFE OPTION - Tells nonmem not to scan StdIn for control characters + --background RAW NMFE OPTION - tell NONMEM not to scan stdin for control characters -d, --debug debug mode - --json json tree of output, if possible - --licfile string RAW NMFE OPTION - Specify a license file to use with NMFE (Nonmem) - --maxlim int RAW NMFE OPTION - Set the maximum values for the buffers used by Nonmem (if 0, don't pass -maxlim to nmfe) (default 2) - --mpi_exec_path string The fully qualified path to mpiexec. Used for nonmem parallel operations (default "/usr/local/mpich3/bin/mpiexec") - --nm_version string Version of nonmem from the configuration list to use - --nmqual Whether or not to execute with nmqual (autolog.pl) - --nobuild RAW NMFE OPTION - Skips recompiling and rebuilding on nonmem executable + --json show JSON output, if possible + --licfile string RAW NMFE OPTION - NONMEM license file to use + --maxlim int RAW NMFE OPTION - set the maximum values for the buffers used by NONMEM (if 0, don't pass -maxlim to nmfe) (default 2) + --mpi_exec_path string fully qualified path to mpiexec to use for NONMEM parallel operations (default "/usr/local/mpich3/bin/mpiexec") + --nm_version string version of NONMEM from the configuration list to use + --nmqual whether to execute with nmqual (autolog.pl) + --nobuild RAW NMFE OPTION - do not build a new NONMEM executable -o, --output string output file - --parafile string Location of a user-provided parafile to use for parallel execution - --parallel Whether or not to run nonmem in parallel mode - --parallel_timeout int The amount of time to wait for parallel operations in nonmem before timing out (default 2147483647) - --prcompile RAW NMFE OPTION - Forces PREDPP compilation - --prdefault RAW NMFE OPTION - Do not recompile any routines other than FSUBS + --parafile string location of a user-provided parafile to use for parallel execution + --parallel whether to run NONMEM in parallel mode + --parallel_timeout int amount of time to wait for parallel operations in NONMEM before timing out (default 2147483647) + --prcompile RAW NMFE OPTION - forces PREDPP compilation + --prdefault RAW NMFE OPTION - do not recompile any routines other than FSUBS -p, --preview preview action, but don't actually run command - --prsame RAW NMFE OPTION - Indicates to nonmem that the PREDPP compilation step should be skipped + --prsame RAW NMFE OPTION - tell NONMEM to skip the PREDPP compilation step --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) - --tprdefault RAW NMFE OPTION - Test if is okay to do -prdefault + --tprdefault RAW NMFE OPTION - test if is okay to do -prdefault -v, --verbose verbose output ``` ### SEE ALSO -* [bbi nonmem](bbi_nonmem.md) - nonmem a (set of) models locally or on the grid +* [bbi nonmem](bbi_nonmem.md) - Entry point for NONMEM-related subcommands diff --git a/docs/commands/bbi_version.md b/docs/commands/bbi_version.md index 287df00c..ee13d4ec 100644 --- a/docs/commands/bbi_version.md +++ b/docs/commands/bbi_version.md @@ -1,12 +1,6 @@ ## bbi version -check version - -### Synopsis - -check the current bbi version -bbi version - +Print bbi's version and exit ``` bbi version [flags] @@ -22,7 +16,7 @@ bbi version [flags] ``` -d, --debug debug mode - --json json tree of output, if possible + --json show JSON output, if possible -o, --output string output file -p, --preview preview action, but don't actually run command --threads int number of threads to execute with locally or nodes to execute on in parallel (default 4) @@ -31,5 +25,5 @@ bbi version [flags] ### SEE ALSO -* [bbi](bbi.md) - manage and execute models +* [bbi](bbi.md) - Manage and execute models diff --git a/docs/site/.gitignore b/docs/site/.gitignore new file mode 100644 index 00000000..d6a86d88 --- /dev/null +++ b/docs/site/.gitignore @@ -0,0 +1,7 @@ +/.hugo_build.lock +/content/**/*.md +!/content/docs/_index.md +/local.mk +/public/ +/resources/ +/static/windows.png diff --git a/docs/site/Makefile b/docs/site/Makefile new file mode 100644 index 00000000..e3038927 --- /dev/null +++ b/docs/site/Makefile @@ -0,0 +1,53 @@ +-include local.mk + +HTTP_PORT ?= 1313 + +version := $(shell git describe --tags --always HEAD) +export HUGO_PARAMS_BBIVERSION ?= $(version) + +.PHONY: help +help: + $(info Primary targets:) + $(info * build: build site under public/) + $(info * serve: build and serve the site locally with 'hugo server') + @: + +.PHONY: build +build: prep + hugo --gc --minify + +.PHONY: serve +serve: prep + hugo server -p '$(HTTP_PORT)' + +copied_files = content/_index.md +copied_files += content/news.md + +.PHONY: prep +prep: commands +prep: $(copied_files) + rm -rf public resources + +command_dir = content/docs/commands + +.PHONY: commands +commands: + rm -rf '$(command_dir)' + ./scripts/ingest-command-docs '$(command_dir)' + +content/_index.md: ../../README.md + grep -vF 'https://goreportcard.com/badge/' '$<' >'$@' + +content/news.md: ./scripts/add-gh-links +content/news.md: ../../NEWS.md + printf -- '---\ntitle: "News"\n---\n\n' >'$@' + sed 's/^#/##/' '$<' | \ + sed 's/^## bbi/##/' | \ + sed 's/^## babylon/##/' | \ + ./scripts/add-gh-links https://github.com/metrumresearchgroup/bbi \ + >>'$@' + +.PHONY: clean +clean: + rm -rf public resources $(command_dir) + rm -f $(copied_files) diff --git a/docs/site/README.md b/docs/site/README.md new file mode 100644 index 00000000..a7a210ec --- /dev/null +++ b/docs/site/README.md @@ -0,0 +1,57 @@ +This directory contains files for building the GitHub Pages site with +[Hugo][h] and the [Hextra][x] theme. The site is published on release +via GitHub Actions ([workflow](/.github/workflows/site.yaml)). + +[h]: https://gohugo.io/ +[x]: https://imfing.github.io/hextra/ + +## Previewing the site + + * Install Hugo () + + * Run `make serve` to prepare the necessary files and launch + [Hugo's web server](https://gohugo.io/commands/hugo_server/) + +## Components + + * [hugo.yaml](./hugo.yaml): site configuration + + * [Hugo docs](https://gohugo.io/getting-started/configuration/) + + * [Hextra docs](https://imfing.github.io/hextra/docs/guide/configuration/) + + * [go.mod](./go.mod): defines Hextra as a Hugo module + + * [Hugo docs](https://gohugo.io/hugo-modules/) + + * [Hextra docs](https://imfing.github.io/hextra/docs/getting-started/#setup-hextra-as-hugo-module) + + * [content/][c]: Markdown content of the site + + Most of the content is pulled from other spots in the repository by + the [Makefile][m], including [NEWS.md](/NEWS.md) and the + command-line Markdown documentation at + [docs/commands/](/docs/commands). + + * [Hugo docs](https://gohugo.io/content-management/) + + * [layouts/](./layouts): templates for rendering the site pages + + Most of the layouts are defined by the Hextra theme. The files + here override particular templates. They are derived from the + corresponding Hextra template. The header of each template + documents what was changed. + + * [Hugo docs](https://gohugo.io/templates/) + + * [scripts/](./scripts): custom scripts used by the [Makefile][m] to + process the Markdown content before writing it to [content/][c] + + This is responsible for things like adding PR links in the NEWS + page rendered on the site. + + * [static/](./static): this directory contains the logos and any + other images used on the site + +[c]: ./content +[m]: ./Makefile diff --git a/docs/site/content/docs/_index.md b/docs/site/content/docs/_index.md new file mode 100644 index 00000000..169af9a8 --- /dev/null +++ b/docs/site/content/docs/_index.md @@ -0,0 +1,18 @@ +--- +title: Documentation +toc: false +--- + +This documentation describes the bbi [command-line interface][commands]. +Below are some of the key commands. + +{{< cards >}} + {{< card link="commands/init" title="bbi init" icon="terminal" + subtitle="Initialize a directory for running bbi" >}} + {{< card link="commands/nonmem_run" title="bbi nonmem run" icon="terminal" + subtitle="Run a NONMEM model" >}} + {{< card link="commands/nonmem_summary" title="bbi nonmem summary" icon="terminal" + subtitle="Summarize the results of a NONMEM model" >}} +{{< /cards >}} + +[commands]: {{< relref "/docs/commands" >}} diff --git a/docs/site/go.mod b/docs/site/go.mod new file mode 100644 index 00000000..5948b8a6 --- /dev/null +++ b/docs/site/go.mod @@ -0,0 +1,5 @@ +module github.com/metrumresearchgroup/bbi/docs/site + +go 1.21.4 + +require github.com/imfing/hextra v0.8.2 // indirect diff --git a/docs/site/go.sum b/docs/site/go.sum new file mode 100644 index 00000000..ed34ce09 --- /dev/null +++ b/docs/site/go.sum @@ -0,0 +1,4 @@ +github.com/imfing/hextra v0.8.1 h1:HPeuyBTxaG7o2PHT9XRgFTVbCVGhJbZ0t7PjApA32F8= +github.com/imfing/hextra v0.8.1/go.mod h1:cEfel3lU/bSx7lTE/+uuR4GJaphyOyiwNR3PTqFTXpI= +github.com/imfing/hextra v0.8.2 h1:/IykSIAywgKfhKUBgAW+dCCjrJWJNny4jr9qvdXfch0= +github.com/imfing/hextra v0.8.2/go.mod h1:cEfel3lU/bSx7lTE/+uuR4GJaphyOyiwNR3PTqFTXpI= diff --git a/docs/site/hugo.yaml b/docs/site/hugo.yaml new file mode 100644 index 00000000..736f5df6 --- /dev/null +++ b/docs/site/hugo.yaml @@ -0,0 +1,54 @@ +title: bbi +baseURL: https://metrumresearchgroup.github.io/bbi/ +languageCode: en-us +markup: + highlight: + noClasses: false + goldmark: + extensions: + typographer: + # Prevent --option in command pages from being rendered with an en-dash. + disable: true + parser: + attribute: + block: true +menu: + main: + - name: Docs + pageRef: /docs + weight: 10 + - name: News + pageRef: /news + weight: 20 + - name: Search + weight: 30 + params: + type: search + - name: GitHub + weight: 40 + url: https://github.com/metrumresearchgroup/bbi + params: + icon: github + sidebar: + - identifier: bbr + name: "bbr: R interface to bbi ↗" + url: "https://metrumresearchgroup.github.io/bbr" + weight: 100 + +disableKinds: + - taxonomy + - term + +module: + imports: + - path: github.com/imfing/hextra +params: + navbar: + displayTitle: true + displayLogo: true + logo: + path: logo.png + width: 25 + theme: + default: system + displayToggle: false diff --git a/docs/site/layouts/_default/_markup/render-blockquote.html b/docs/site/layouts/_default/_markup/render-blockquote.html new file mode 100644 index 00000000..5204b6a9 --- /dev/null +++ b/docs/site/layouts/_default/_markup/render-blockquote.html @@ -0,0 +1,47 @@ +{{/* + This is combines the types from the example at + with the + classes from Hextra's layouts/shortcodes/callout.html + (blob: 6b56bcb2fff52b58af2a34da0bd8e5784108bd2b). +*/}} +{{ if eq .Type "alert" }} + {{ $emojis := dict + "caution" ":exclamation:" + "important" ":information_source:" + "note" ":information_source:" + "tip" ":bulb:" + "warning" ":information_source:" + }} + + {{ $orange := "hx-border-orange-100 hx-bg-orange-50 hx-text-orange-800 dark:hx-border-orange-400/30 dark:hx-bg-orange-400/20 dark:hx-text-orange-300" }} + {{ $blue := "hx-border-blue-200 hx-bg-blue-100 hx-text-blue-900 dark:hx-border-blue-200/30 dark:hx-bg-blue-900/30 dark:hx-text-blue-200" }} + {{ $yellow := "hx-border-yellow-100 hx-bg-yellow-50 hx-text-yellow-900 dark:hx-border-yellow-200/30 dark:hx-bg-yellow-700/30 dark:hx-text-yellow-200" }} + {{ $red := "hx-border-red-200 hx-bg-red-100 hx-text-red-900 dark:hx-border-red-200/30 dark:hx-bg-red-900/30 dark:hx-text-red-200" }} + + {{ $classes := dict + "caution" $red + "important" $orange + "note" $blue + "tip" $blue + "warning" $yellow + }} + + {{ $class := (index $classes .AlertType) }} +
+
+
+ {{ transform.Emojify (index $emojis .AlertType) }} +
+
+ +
+
+ {{ .Text | safeHTML }} +
+
+
+{{ else }} +
+ {{ .Text | safeHTML }} +
+{{ end }} diff --git a/docs/site/layouts/command/list.html b/docs/site/layouts/command/list.html new file mode 100644 index 00000000..74a60b73 --- /dev/null +++ b/docs/site/layouts/command/list.html @@ -0,0 +1,25 @@ +{{/* + This is modified from Hextra's layouts/docs/list.html + (blob: a91882ae16796158309d93c44a3df571b98dfb11) + + Changes: + + * don't insert title as H1 heading +*/}} +{{ define "main" }} +
+ {{ partial "sidebar.html" (dict "context" .) }} + {{ partial "toc.html" . }} +
+
+ {{ partial "breadcrumb.html" . }} +
+ {{ .Content }} +
+ {{ partial "components/last-updated.html" . }} + {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+
+{{ end }} diff --git a/docs/site/layouts/command/single.html b/docs/site/layouts/command/single.html new file mode 100644 index 00000000..51891e3e --- /dev/null +++ b/docs/site/layouts/command/single.html @@ -0,0 +1,25 @@ +{{/* + This is modified from Hextra's layouts/docs/single.html + (blob: a91882ae16796158309d93c44a3df571b98dfb11) + + Changes: + + * don't insert title as H1 heading +*/}} +{{ define "main" }} +
+ {{ partial "sidebar.html" (dict "context" .) }} + {{ partial "toc.html" . }} +
+
+ {{ partial "breadcrumb.html" . }} +
+ {{ .Content }} +
+ {{ partial "components/last-updated.html" . }} + {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+
+{{ end }} diff --git a/docs/site/layouts/partials/favicons.html b/docs/site/layouts/partials/favicons.html new file mode 100644 index 00000000..2d659c3b --- /dev/null +++ b/docs/site/layouts/partials/favicons.html @@ -0,0 +1,13 @@ +{{/* + This is modified from Hextra's layouts/partials/favicons.html + (blob: 66a80188e72c094884b37ff9720d669a6e03824f) + + Changes: + + * remove links to favicon.svg and favicon-dark.svg +*/}} + + + + + diff --git a/docs/site/layouts/partials/footer.html b/docs/site/layouts/partials/footer.html new file mode 100644 index 00000000..787c46fe --- /dev/null +++ b/docs/site/layouts/partials/footer.html @@ -0,0 +1,35 @@ +{{/* + This is modified from Hextra's layouts/partials/footer.html + (blob: 61cbb1133d633b0389f9d6ce70cd99b8568a7bad) + + Changes: + + * remove support for toggling (handled in navbar instead) + + * decrease height of footer + + * use custom credit line that 1) credits Hugo in addition to + Hextra and 2) is right aligned +*/}} + +{{- $footerWidth := "hx-max-w-screen-xl" -}} +{{- with .Site.Params.footer.width -}} + {{ if eq . "wide" -}} + {{ $footerWidth = "hx-max-w-[90rem]" -}} + {{ else if eq . "full" -}} + {{ $footerWidth = "max-w-full" -}} + {{ end -}} +{{- end -}} + +
+
+ + Site built with + Hugo + and + Hextra + +
+
diff --git a/docs/site/layouts/partials/navbar.html b/docs/site/layouts/partials/navbar.html new file mode 100644 index 00000000..8c9d7543 --- /dev/null +++ b/docs/site/layouts/partials/navbar.html @@ -0,0 +1,89 @@ +{{/* + This is modified from Hextra's layouts/partials/navbar.html + (blob: 04adb27e4f170601cc82f9d8ecf30baf50ffbe5a) + + Changes: + + * add bbi version + + * don't blur + + * add dark/light theme toggle (but don't guard it with + site.Params.theme.displayToggle so that Hexta's sidebar can be + used without any changes) +*/}} + +{{- $logoPath := .Site.Params.navbar.logo.path | default "images/logo.svg" -}} +{{- $logoLink := .Site.Params.navbar.logo.link | default .Site.Home.RelPermalink -}} +{{- $logoWidth := .Site.Params.navbar.logo.width | default "20" -}} +{{- $logoHeight := .Site.Params.navbar.logo.height | default "20" -}} +{{- $logoDarkPath := .Site.Params.navbar.logo.dark | default $logoPath -}} + +{{- $bbiVersion := .Site.Params.bbiversion | default "" -}} + +{{- $navWidth := "hx-max-w-[90rem]" -}} +{{- with .Site.Params.navbar.width -}} + {{ if eq . "normal" -}} + {{ $navWidth = "hx-max-w-screen-xl" -}} + {{ else if eq . "full" -}} + {{ $navWidth = "max-w-full" -}} + {{ end -}} +{{- end -}} + +
+
+ + +
diff --git a/docs/site/layouts/partials/theme-toggle.html b/docs/site/layouts/partials/theme-toggle.html new file mode 100644 index 00000000..2da946d4 --- /dev/null +++ b/docs/site/layouts/partials/theme-toggle.html @@ -0,0 +1,29 @@ +{{/* + This is modified from Hextra's layouts/partials/favicons.html + (blob: 6a939b56760c8f2b7ca442463ee41b47a65b6091) + + Changes: + + * increase size of icons +*/}} +{{- $hideLabel := .hideLabel | default false -}} + +{{- $changeTheme := (T "changeTheme") | default "Change theme" -}} +{{- $light := (T "light") | default "Light" -}} +{{- $dark := (T "dark") | default "Dark" -}} + + + diff --git a/docs/site/scripts/add-gh-links b/docs/site/scripts/add-gh-links new file mode 100755 index 00000000..e4420dd0 --- /dev/null +++ b/docs/site/scripts/add-gh-links @@ -0,0 +1,74 @@ +#!/usr/bin/env python3 +# Copyright 2024 Metrum Research Group +# SPDX-License-Identifier: MIT +"""usage: {} + +Read markdown content from stdin and write it to stdout replacing + + * #NNN with [#NNN](/issue/NNN) + + * commit IDs with links to [](/commit/) + + If something looks like a commit but isn't a known commit in the + current repository, it's left as is. + +This script must be executed from a Git repository. +""" + +import fileinput +import re +import subprocess as sp +import sys + +link_re = re.compile(r"\B#([1-9][0-9]*)\b") + + +def link_issues(url, string): + return link_re.sub(rf"[#\1]({url}/issues/\1)", string) + + +commit_re = re.compile(r"\b([0-9a-f]{7,})\b") + + +# Note: This runs a git process per commit candidate. If this were to +# be used in a case where there is a large amount of input and +# performance matters, consider rewriting to use cat-file and a single +# process. +def replace_commit(matchobj): + fullmatch = matchobj.group(0) + commit = matchobj.group(1) + + try: + p = sp.run( + ["git", "rev-parse", "--verify", "--quiet", commit + "^{commit}"], + check=True, + capture_output=True, + encoding="utf-8", + ) + except sp.CalledProcessError as err: + if err.returncode == 1: + # This doesn't resolve to a known commit. + return fullmatch + raise + + resolved = p.stdout.rstrip("\n") + return fullmatch.replace(commit, f"[{commit}]({url}/commit/{resolved})") + + +def link_commits(url, string): + return commit_re.sub(replace_commit, string) + + +if __name__ == "__main__": + if len(sys.argv) != 2: + sys.stderr.write(__doc__.format(sys.argv[0])) + sys.exit(1) + + url = sys.argv[1] + if url.endswith("/"): + url = url[:-1] + + for line in fileinput.input("-"): + line = link_issues(url, line) + line = link_commits(url, line) + sys.stdout.write(line) diff --git a/docs/site/scripts/format-command-flags b/docs/site/scripts/format-command-flags new file mode 100755 index 00000000..e9c2a413 --- /dev/null +++ b/docs/site/scripts/format-command-flags @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +""" +Read Cobra command markdown on stdin and replace option code blocks +with a list of options. + +For example, convert + + ``` + --json json tree of output, if possible + -v, --verbose verbose output + ``` + +to + + * `--json`: json tree of output, if possible + + * `-v, --verbose`: verbose output + +""" + +import fileinput +import sys + + +def format_option(line): + line = line.strip() + if not line: + return "" + if line == "```": + return "\n" + + try: + # Note: This relies on the "-o, --option value" part 1) _not_ + # containing two spaces and 2) being separated from the + # description by at least two spaces. + opts, desc = line.split(" ", maxsplit=1) + except ValueError: + raise ValueError(f"option line in unexpected format: {line}") from None + + return f" * `{opts}`: {desc}\n\n" + + +if __name__ == "__main__": + in_options = False + for line in fileinput.input("-"): + if line.startswith("#"): + in_options = line.startswith("### Options") + sys.stdout.write(line) + continue + + if in_options: + line = format_option(line) + sys.stdout.write(line) diff --git a/docs/site/scripts/ingest-command-docs b/docs/site/scripts/ingest-command-docs new file mode 100755 index 00000000..2f79f0d3 --- /dev/null +++ b/docs/site/scripts/ingest-command-docs @@ -0,0 +1,58 @@ +#!/bin/sh + +# Copy generated command docs from contents/commands/ with the +# following modifications: +# +# * set title metadata to name of subcommand +# +# * promote each heading (e.g., H2 becomes H1) +# +# * adjust the link to the other markdown files to work in the Hugo +# context +# +# * tweak the headings of top-level command page to make it a more +# suitable landing page for /commands +# +# * replace "option" with "flag" in title. +# +# Although "option" is arguably the better term in general, 1) +# cobra puts these under "flags" in its command-line help output +# and 2) cobra adds a "[flag]" value to the usage, so staying with +# "flag" is better for consistency. +# +# * put inherited flags as subhead of under flags heading +# +# * extract option lines from code block and reformat as bullets + +set -eu + +test -x scripts/format-command-flags || { + printf >&2 'script must be executed from docs/site/ directory\n' + exit 1 +} + +outdir=content/docs/commands +mkdir -p "$outdir" +for f in ../commands/*.md +do + if test "$f" = ../commands/bbi.md + then + dest=$outdir/_index.md + title=Commands + seename=Subcommands + else + base=$(basename "$f") + cmd=${base%.md} + title=$(printf '%s\n' "$cmd" | sed 's/bbi_//' | sed 's/_/ /g') + dest=$outdir/${base#bbi_} + seename='See also' + fi + printf -- '---\ntitle: "%s"\ntype: "command"\n---\n\n' "$title" >"$dest" + ./scripts/format-command-flags <"$f" | \ + sed 's/^##/#/' | \ + sed -E 's|\[bbi\]\(bbi\.md\).*|[bbi]({{< relref "/docs/commands/" >}}) - top-level entry point |' | \ + sed 's|(bbi_\(.*\)\.md)|({{< relref "/docs/commands/\1" >}})|' | \ + sed 's/# Options inherited from parent commands/## Inherited/' | \ + sed 's/# Options/# Flags/' | \ + sed "s/# SEE ALSO/# $seename/" >>"$dest" +done diff --git a/docs/site/static/apple-touch-icon-120x120.png b/docs/site/static/apple-touch-icon-120x120.png new file mode 100644 index 00000000..9a7b092c Binary files /dev/null and b/docs/site/static/apple-touch-icon-120x120.png differ diff --git a/docs/site/static/apple-touch-icon-152x152.png b/docs/site/static/apple-touch-icon-152x152.png new file mode 100644 index 00000000..3daee701 Binary files /dev/null and b/docs/site/static/apple-touch-icon-152x152.png differ diff --git a/docs/site/static/apple-touch-icon-180x180.png b/docs/site/static/apple-touch-icon-180x180.png new file mode 100644 index 00000000..13a57a3f Binary files /dev/null and b/docs/site/static/apple-touch-icon-180x180.png differ diff --git a/docs/site/static/apple-touch-icon-60x60.png b/docs/site/static/apple-touch-icon-60x60.png new file mode 100644 index 00000000..c39fd21d Binary files /dev/null and b/docs/site/static/apple-touch-icon-60x60.png differ diff --git a/docs/site/static/apple-touch-icon-76x76.png b/docs/site/static/apple-touch-icon-76x76.png new file mode 100644 index 00000000..45eb5e09 Binary files /dev/null and b/docs/site/static/apple-touch-icon-76x76.png differ diff --git a/docs/site/static/apple-touch-icon.png b/docs/site/static/apple-touch-icon.png new file mode 100644 index 00000000..a2d8c610 Binary files /dev/null and b/docs/site/static/apple-touch-icon.png differ diff --git a/docs/site/static/favicon-16x16.png b/docs/site/static/favicon-16x16.png new file mode 100644 index 00000000..6c11c070 Binary files /dev/null and b/docs/site/static/favicon-16x16.png differ diff --git a/docs/site/static/favicon-32x32.png b/docs/site/static/favicon-32x32.png new file mode 100644 index 00000000..50fffcc1 Binary files /dev/null and b/docs/site/static/favicon-32x32.png differ diff --git a/docs/site/static/favicon.ico b/docs/site/static/favicon.ico new file mode 100644 index 00000000..b97093a9 Binary files /dev/null and b/docs/site/static/favicon.ico differ diff --git a/docs/site/static/logo.png b/docs/site/static/logo.png new file mode 100644 index 00000000..1f759648 Binary files /dev/null and b/docs/site/static/logo.png differ