wrap errors, add example and update markdown code langauge

Signed-off-by: Justin Alvarez <[email protected]>

cmd/finch/doc.TEMPLATE

@@ -6,7 +6,7 @@
 
 {{.Properties}}
 
-{{end}}```bash
+{{end}}```text
 {{ .Usage }}
 ```{{if gt (len .Aliases) 0}}
 
@@ -22,13 +22,13 @@
 
 ## Commands
 
-```bash
+```text
 {{ .Commands }}
 ```{{end}}{{if gt (len .Options) 0}}
 
 ## Options
 
-```bash
+```text
 {{ .Options }}
 ```{{end}}{{if gt (len .SeeAlso) 0}}
 

cmd/finch/gen_docs.go

@@ -103,7 +103,7 @@ func (gd *genDocsAction) run(outDir string) error {
 func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) error {
 	for _, c := range cmd.Commands() {
 		if err := gd.captureHelpOutput(c, outDir); err != nil {
-			return err
+			return fmt.Errorf("error while generating docs for %s: %w", c.CommandPath(), err)
 		}
 	}
 
@@ -150,6 +150,10 @@ func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) er
 		return fmt.Errorf("error while reading stdout from pipe: %w", err)
 	}
 
+	// Link to parent command page if parent command is also runnable.
+	// For example, if `finch vm` and `finch vm init` both had their own Run/RunE methods defined,
+	// finch vm init's documentation page would link to finch vm's page.
+	// If this condition is not met, then there is no "SEE ALSO" section.
 	seeAlso := ""
 	if cmd.HasParent() && cmd.Parent().Runnable() {
 		parentName := cmd.Parent().CommandPath()

cmd/finch/gen_docs_test.go

@@ -95,7 +95,7 @@ func TestGenDocsAction_runAdapter(t *testing.T) {
 				require.NoError(t, err)
 				require.Equal(t, string(buf), fmt.Sprintf(`# test-command
 
-%sbash
+%stext
   test-command [flags]
 %s
 `, codeBlock, codeBlock))

docs/cmd/finch_build.md

@@ -3,13 +3,13 @@
 Build an image from a Dockerfile. Needs buildkitd to be running.
 If Dockerfile is not present and -f is not specified, it will look for Containerfile and build with it.
 
-```bash
+```text
 finch build [flags] PATH
 ```
 
 ## Options
 
-```bash
+```text
       --build-arg stringArray    Set build-time variables
       --buildkit-host string     BuildKit address [$BUILDKIT_HOST] (default "unix:///run/buildkit/buildkitd.sock")
       --cache-from stringArray   External cache sources (eg. user/app:cache, type=local,src=path/to/dir)

docs/cmd/finch_builder.md

@@ -2,20 +2,20 @@
 
 Manage builds
 
-```bash
+```text
 finch builder [flags]
 ```
 
 ## Commands
 
-```bash
+```text
   build  Build an image from a Dockerfile. Needs buildkitd to be running.
   debug  Debug Dockerfile
   prune  Clean up BuildKit build cache
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help   help for builder
 ```

docs/cmd/finch_commit.md

@@ -2,13 +2,13 @@
 
 Create a new image from a container's changes
 
-```bash
+```text
 finch commit [flags] CONTAINER REPOSITORY[:TAG]
 ```
 
 ## Options
 
-```bash
+```text
   -a, --author string        Author (e.g., "finch contributor <[email protected]>")
   -c, --change stringArray   Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT])
   -h, --help                 help for commit

docs/cmd/finch_completion_bash.md

@@ -13,13 +13,13 @@ To load completions for every new session, execute once:
 
 ####
 
-```bash
+```text
   finch completion bash
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help              help for bash
       --no-descriptions   disable completion descriptions
 ```

docs/cmd/finch_completion_fish.md

@@ -12,13 +12,13 @@ To load completions for every new session, execute once:
 
 You will need to start a new shell for this setup to take effect.
 
-```bash
+```text
   finch completion fish [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help              help for fish
       --no-descriptions   disable completion descriptions
 ```

docs/cmd/finch_completion_powershell.md

@@ -9,13 +9,13 @@ To load completions in your current shell session:
 To load completions for every new session, add the output of the above command
 to your powershell profile.
 
-```bash
+```text
   finch completion powershell [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help              help for powershell
       --no-descriptions   disable completion descriptions
 ```

docs/cmd/finch_completion_zsh.md

@@ -15,13 +15,13 @@ To load completions for every new session, execute once:
 
 ####
 
-```bash
+```text
   finch completion zsh [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help              help for zsh
       --no-descriptions   disable completion descriptions
 ```

docs/cmd/finch_compose.md

@@ -2,13 +2,13 @@
 
 Compose
 
-```bash
+```text
 finch compose [flags] COMMAND
 ```
 
 ## Commands
 
-```bash
+```text
   build    Build or rebuild services
   config   Validate and view the Compose file
   cp       Copy files/folders between a service container and the local filesystem
@@ -36,7 +36,7 @@ finch compose [flags] COMMAND
 
 ## Options
 
-```bash
+```text
       --env-file string            Specify an alternate environment file
   -f, --f stringArray              Alias of --file
       --file stringArray           Specify an alternate compose file

docs/cmd/finch_container.md

@@ -2,13 +2,13 @@
 
 Manage containers
 
-```bash
+```text
 finch container [flags]
 ```
 
 ## Commands
 
-```bash
+```text
   attach   Attach stdin, stdout, and stderr to a running container.
   commit   Create a new image from a container's changes
   cp       Copy files/folders between a running container and the local filesystem.
@@ -35,6 +35,6 @@ finch container [flags]
 
 ## Options
 
-```bash
+```text
   -h, --help   help for container
 ```

docs/cmd/finch_cp.md

@@ -5,14 +5,14 @@ This command requires 'tar' to be installed on the host (not in the container).
 Using GNU tar is recommended.
 The path of the 'tar' binary can be specified with an environment variable '$TAR'.
 
-```bash
+```text
 finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|-
   finch cp [flags] SRC_PATH|- CONTAINER:DEST_PATH
 ```
 
 ## Options
 
-```bash
+```text
   -L, --follow-link   Always follow symbolic link in SRC_PATH.
   -h, --help          help for cp
 ```

docs/cmd/finch_create.md

@@ -2,13 +2,13 @@
 
 Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS.
 
-```bash
+```text
 finch create [flags] IMAGE [COMMAND] [ARG...]
 ```
 
 ## Options
 
-```bash
+```text
       --add-host strings                               Add a custom host-to-IP mapping (host:ip)
       --blkio-weight uint16                            Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)
       --cap-add strings                                Add Linux capabilities

docs/cmd/finch_events.md

@@ -2,13 +2,13 @@
 
 Get real time events from the server
 
-```bash
+```text
 finch events [flags]
 ```
 
 ## Options
 
-```bash
+```text
       --format string   Format the output using the given Go template, e.g, '{{json .}}'
   -h, --help            help for events
 ```

docs/cmd/finch_exec.md

@@ -2,13 +2,13 @@
 
 Run a command in a running container
 
-```bash
+```text
 finch exec [flags] CONTAINER COMMAND [ARG...]
 ```
 
 ## Options
 
-```bash
+```text
   -d, --detach             Detached mode: run command in the background
   -e, --env stringArray    Set environment variables
       --env-file strings   Set environment variables from file

docs/cmd/finch_help.md

@@ -3,12 +3,12 @@
 Help provides help for any command in the application.
 Simply type finch help [path to command] for full details.
 
-```bash
+```text
   finch help [command] [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -h, --help   help for help
 ```

docs/cmd/finch_history.md

@@ -2,13 +2,13 @@
 
 Show the history of an image
 
-```bash
+```text
 finch history [flags] IMAGE
 ```
 
 ## Options
 
-```bash
+```text
   -f, --format string   Format the output using the given Go template, e.g, '{{json .}}'
   -h, --help            help for history
       --no-trunc        Don't truncate output

docs/cmd/finch_image.md

@@ -2,13 +2,13 @@
 
 Manage images
 
-```bash
+```text
 finch image [flags]
 ```
 
 ## Commands
 
-```bash
+```text
   build    Build an image from a Dockerfile. Needs buildkitd to be running.
   convert  convert an image
   decrypt  decrypt an image
@@ -27,6 +27,6 @@ finch image [flags]
 
 ## Options
 
-```bash
+```text
   -h, --help   help for image
 ```

docs/cmd/finch_images.md

@@ -13,13 +13,13 @@ List images
 - SIZE:       Size of the unpacked snapshots
 - BLOB SIZE:  Size of the blobs (such as layer tarballs) in the content store
 
-```bash
+```text
 finch images [flags] [REPOSITORY[:TAG]]
 ```
 
 ## Options
 
-```bash
+```text
   -a, --all              (unimplemented yet, always true) (default true)
       --digests          Show digests (compatible with Docker, unlike ID)
   -f, --filter strings   Filter output based on conditions provided

docs/cmd/finch_info.md

@@ -2,13 +2,13 @@
 
 Display system-wide information
 
-```bash
+```text
 finch info [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -f, --format string   Format the output using the given Go template, e.g, '{{json .}}'
   -h, --help            help for info
       --mode string     Information mode, "dockercompat" for Docker-compatible output, "native" for containerd-native output (default "dockercompat")

docs/cmd/finch_inspect.md

@@ -2,13 +2,13 @@
 
 Return low-level information on objects.
 
-```bash
+```text
 finch inspect [flags]
 ```
 
 ## Options
 
-```bash
+```text
   -f, --format string   Format the output using the given Go template, e.g, '{{json .}}'
   -h, --help            help for inspect
       --mode string     Inspect mode, "dockercompat" for Docker-compatible output, "native" for containerd-native output (default "dockercompat")