Update documentation

zph · zph · commit c0b23a0a1f31 · 2024-08-05T19:55:36.000-07:00
diff --git a/README.md b/README.md
@@ -1,21 +1,14 @@
 # tome-cli
 
-
 A rewrite of [`sub`](https://github.com/qrush/sub) and [`tome`](https://github.com/toumorokoshi/tome) and my fork of [tome](https://github.com/zph/tome) but with a different internal implementation in order to support:
 1. Improved auto-completion
 2. Improved usage/help outputs
 3. Faster development
 4. Testable interfaces
 
-# Interface
+# Usage
 
 ```
-export TOME_ROOT=examples
-tome-cli exec path to file
-tome-cli help path to <TAB>
-tome-cli completion fish | source
-tome-cli alias --write kit
-
 # shorthand syntax via bash wrapper script
 tome-cli --executable kit alias --output ~/bin/kit
 
@@ -24,11 +17,37 @@ kit completion fish | source
 kit path to file
 kit pat<TAB>
 
+# Long form
+export TOME_ROOT=examples
+tome-cli exec path to file
+tome-cli help path to <TAB>
+tome-cli completion fish | source
+
+# Setup tab completion
+tome-cli completion fish | source
+eval "$(tome-cli completion zsh)"
 
-# Print out completions for zsh | fish | bash
-tome completion zsh
+# See instructions for a command
+tome-cli completion --help
 ```
 
+See [docs](./docs/tome-cli.md) for expanded instructions
+
+# Features
+
+- Organize a folder of scripts into a CLI sdk
+- Any language is supported via normal script `#!`
+- Usage text extracted from script header if `USAGE: ` is included in leading comments
+- Full help text extracted as lines from `USAGE: ` to first empty line
+- Builtin alias generator allows for embedding configuration flags via tome-cli [alias](./docs/tome-cli_alias.md)
+- Auto completion of:
+  - subcommands (exec, help, etc)
+  - root folder's folder names
+  - root folder's scripts
+  - root script's flags and arguments (when they satisfy the --complete and TOME_COMPLETION interface)
+- Gitignore like syntax for ignoring scripts by using a `.tome_ignore` file at base of root folder
+-
+
 # Capabilities
 
 - [x] exec scripts in a directory
@@ -51,8 +70,8 @@ tome completion zsh
 - [x] auto-complete script arguments (scripts that include the text TOME_COMPLETION which are tab completed will try to get autocompletes from the script via executing it with --completion)
 - [x] injects TOME_ROOT into tooling as env var and TOME_EXECUTABLE
 - [x] Add level and k/v style logging
-- [ ] Add instructions to README
-- [ ] Generate a docs folder for more full instructions (https://umarcor.github.io/cobra/#generating-markdown-docs-for-your-own-cobracommand)
+- [x] Add instructions to README
+- [x] Generate a docs folder for more full instructions (https://umarcor.github.io/cobra/#generating-markdown-docs-for-your-own-cobracommand)
 - [ ] See if there's utility in ActiveHelp https://umarcor.github.io/cobra/#active-help
 - [ ] pre-hooks (hooks.d folder will be sourced in order or executed before the real script)
   - [ ] https://umarcor.github.io/cobra/#prerun-and-postrun-hooks
@@ -68,9 +87,3 @@ tome completion zsh
 ## Non Features
 
 - Does not support sourcing scripts into shell environment because it adds implementation complexity for other core commands
-
-# Alternate names
-
-kit
-edc or eds (everyday scripting)
-grimoire
diff --git a/cmd/alias.go b/cmd/alias.go
@@ -28,8 +28,24 @@ var aliasCmd = &cobra.Command{
 	Use:   "alias",
 	Short: "Create an alias wrapper for tome-cli",
 	Long: `The alias command allows you to create an alias for the tome command.
-This can be useful if you wish to embed common flags like root and executable name and alias the command as a different name.
-The generated script uses the executable name and root directory specified in the tome configuration file.`,
+
+The alias command allows you to create an alias for the tome command.
+
+An alias is a shell script that embeds common flags like root and executable
+name and can be stored as an alternate name.
+
+The generated script uses the executable name and root directory specified in the tome configuration file.
+
+To use it:
+
+	The following command will create an alias script in the ~/bin directory named 'kit'
+	which embeds the root directory and executable name so that 'kit' can be used in normal
+	circumstances with no flags or environment variables.
+
+  $> tome-cli --root $PWD/examples --executable kit alias --output ~/bin/kit
+
+Read the template script 'tome-wrapper.sh.tmpl' for more information on how the alias is created
+`,
 	Run: func(cmd *cobra.Command, args []string) {
 		config := NewConfig()
 		s := ScriptTemplate{
diff --git a/cmd/completion.go b/cmd/completion.go
@@ -55,6 +55,18 @@ PowerShell:
   # To load completions for every new session, run:
   PS> %[1]s completion powershell > %[1]s.ps1
   # and source this file from your PowerShell profile.
+
+Using completions from within child scripts
+
+Once completions discover an executable and non-ignored script,
+tome-cli will check if the script has TOME_COMPLETION declared in file.
+If so, it will attempt fetch completions from the script itself.
+
+This is accomplished by passing --complete to the script and capturing the output.
+
+The output syntax is newline-separated strings where each line is composed of
+a completion (e.g. a flag or argument), a tab character, and a description of the completion.
+
 `, rootCmd.Name()),
 	DisableFlagsInUseLine: true,
 	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
diff --git a/cmd/docs.go b/cmd/docs.go
@@ -12,8 +12,11 @@ import (
 
 // docsCmd represents the docs command
 var docsCmd = &cobra.Command{
-	Use:    "docs",
-	Short:  "Create docs for tome-cli",
+	Use:   "docs",
+	Short: "Create docs for tome-cli",
+	Long: `The docs command generates markdown documentation for the tome-cli command.
+
+	It's hidden from the help menu because it's not a user-facing command.`,
 	Hidden: true,
 	Run: func(cmd *cobra.Command, args []string) {
 		err := doc.GenMarkdownTree(rootCmd, "docs")
diff --git a/cmd/exec.go b/cmd/exec.go
@@ -105,13 +105,23 @@ var execCmd = &cobra.Command{
 	Use:   "exec",
 	Short: "executes a script from tome root",
 	Long: dedent.Dedent(`
-		The exec command executes a script file with the provided arguments.
+	Usage: tome-cli exec <path-to> <script> [args...]
 
-		The exec command will search for the script file in the root directory
-	  specified in the tome configuration flags or env vars.
+	The exec command executes a script file with the provided arguments.
 
-		Scripts are searched for in the root directory and subdirectories and
-		then are called with execvp to replace the current process.
+	The exec command will search for the script file in the root directory
+	specified in the tome configuration flags or env vars. Paths will be
+	joined with the root directory, the intervening directories, and
+	the script file name.
+
+	When executed, the script will be become the tome-cli process through
+	the syscall.Exec function.
+
+	TOME_ROOT and TOME_EXECUTABLE are injected into the environment as well
+	as the executable name as an uppercased snake case string.
+
+	If the executable name is 'kit' the additional environment variables would be:
+	KIT_ROOT, KIT_EXECUTABLE.
 		`),
 	RunE:              ExecRunE,
 	ValidArgsFunction: ValidArgsFunctionForScripts,
diff --git a/docs/tome-cli.md b/docs/tome-cli.md
@@ -32,4 +32,4 @@ tome-cli [flags]
 * [tome-cli exec](tome-cli_exec.md)	 - executes a script from tome root
 * [tome-cli help](tome-cli_help.md)	 - help displays the usage and help text for a script
 
-###### Auto generated by spf13/cobra on 3-Aug-2024
+###### Auto generated by spf13/cobra on 5-Aug-2024
diff --git a/docs/tome-cli_alias.md b/docs/tome-cli_alias.md
@@ -5,9 +5,25 @@ Create an alias wrapper for tome-cli
 ### Synopsis
 
 The alias command allows you to create an alias for the tome command.
-This can be useful if you wish to embed common flags like root and executable name and alias the command as a different name.
+
+The alias command allows you to create an alias for the tome command.
+
+An alias is a shell script that embeds common flags like root and executable
+name and can be stored as an alternate name.
+
 The generated script uses the executable name and root directory specified in the tome configuration file.
 
+To use it:
+
+	The following command will create an alias script in the ~/bin directory named 'kit'
+	which embeds the root directory and executable name so that 'kit' can be used in normal
+	circumstances with no flags or environment variables.
+
+  $> tome-cli --root $PWD/examples --executable kit alias --output ~/bin/kit
+
+Read the template script 'tome-wrapper.sh.tmpl' for more information on how the alias is created
+
+
 ```
 tome-cli alias [flags]
 ```
@@ -31,4 +47,4 @@ tome-cli alias [flags]
 
 * [tome-cli](tome-cli.md)	 - A cli tool to manage scripts as a set of subcommands
 
-###### Auto generated by spf13/cobra on 3-Aug-2024
+###### Auto generated by spf13/cobra on 5-Aug-2024
diff --git a/docs/tome-cli_completion.md b/docs/tome-cli_completion.md
@@ -43,6 +43,18 @@ PowerShell:
   PS> tome-cli completion powershell > tome-cli.ps1
   # and source this file from your PowerShell profile.
 
+Using completions from within child scripts
+
+Once completions discover an executable and non-ignored script,
+tome-cli will check if the script has TOME_COMPLETION declared in file.
+If so, it will attempt fetch completions from the script itself.
+
+This is accomplished by passing --complete to the script and capturing the output.
+
+The output syntax is newline-separated strings where each line is composed of
+a completion (e.g. a flag or argument), a tab character, and a description of the completion.
+
+
 
 ```
 tome-cli completion [bash|zsh|fish|powershell]
@@ -66,4 +78,4 @@ tome-cli completion [bash|zsh|fish|powershell]
 
 * [tome-cli](tome-cli.md)	 - A cli tool to manage scripts as a set of subcommands
 
-###### Auto generated by spf13/cobra on 3-Aug-2024
+###### Auto generated by spf13/cobra on 5-Aug-2024
diff --git a/docs/tome-cli_exec.md b/docs/tome-cli_exec.md
@@ -5,13 +5,23 @@ executes a script from tome root
 ### Synopsis
 
 
-		The exec command executes a script file with the provided arguments.
+Usage: tome-cli exec <path-to> <script> [args...]
 
-		The exec command will search for the script file in the root directory
-	  specified in the tome configuration flags or env vars.
+The exec command executes a script file with the provided arguments.
 
-		Scripts are searched for in the root directory and subdirectories and
-		then are called with execvp to replace the current process.
+The exec command will search for the script file in the root directory
+specified in the tome configuration flags or env vars. Paths will be
+joined with the root directory, the intervening directories, and
+the script file name.
+
+When executed, the script will be become the tome-cli process through
+the syscall.Exec function.
+
+TOME_ROOT and TOME_EXECUTABLE are injected into the environment as well
+as the executable name as an uppercased snake case string.
+
+If the executable name is 'kit' the additional environment variables would be:
+KIT_ROOT, KIT_EXECUTABLE.
 
 
 ```
@@ -37,4 +47,4 @@ tome-cli exec [flags]
 
 * [tome-cli](tome-cli.md)	 - A cli tool to manage scripts as a set of subcommands
 
-###### Auto generated by spf13/cobra on 3-Aug-2024
+###### Auto generated by spf13/cobra on 5-Aug-2024
diff --git a/docs/tome-cli_help.md b/docs/tome-cli_help.md
@@ -48,4 +48,4 @@ tome-cli help [flags]
 
 * [tome-cli](tome-cli.md)	 - A cli tool to manage scripts as a set of subcommands
 
-###### Auto generated by spf13/cobra on 3-Aug-2024
+###### Auto generated by spf13/cobra on 5-Aug-2024

Original file line number	Diff line number	Diff line change
`@@ -48,4 +48,4 @@ tome-cli help [flags]`
`48`	`48`
`49`	`49`	`* [tome-cli](tome-cli.md) - A cli tool to manage scripts as a set of subcommands`
`50`	`50`
`51`		`-###### Auto generated by spf13/cobra on 3-Aug-2024`
	`51`	`+###### Auto generated by spf13/cobra on 5-Aug-2024`