From 0a60880c86ec5571c2f5ed5dcb72904df6c32f1a Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Wed, 18 Oct 2023 19:42:36 -0400 Subject: [PATCH 01/11] feat: auto-generate docs Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE.md | 36 ++++ cmd/finch/gen_docs.go | 224 ++++++++++++++++++++++ cmd/finch/main.go | 1 + docs/cmd/finch_build.md | 34 ++++ docs/cmd/finch_builder.md | 22 +++ docs/cmd/finch_commit.md | 19 ++ docs/cmd/finch_completion_bash.md | 27 +++ docs/cmd/finch_completion_fish.md | 26 +++ docs/cmd/finch_completion_powershell.md | 23 +++ docs/cmd/finch_completion_zsh.md | 29 +++ docs/cmd/finch_compose.md | 49 +++++ docs/cmd/finch_container.md | 41 ++++ docs/cmd/finch_cp.md | 20 ++ docs/cmd/finch_create.md | 97 ++++++++++ docs/cmd/finch_events.md | 16 ++ docs/cmd/finch_exec.md | 23 +++ docs/cmd/finch_gen-docs_generate.md | 16 ++ docs/cmd/finch_help.md | 16 ++ docs/cmd/finch_history.md | 18 ++ docs/cmd/finch_image.md | 33 ++++ docs/cmd/finch_images.md | 32 ++++ docs/cmd/finch_info.md | 17 ++ docs/cmd/finch_inspect.md | 18 ++ docs/cmd/finch_kill.md | 16 ++ docs/cmd/finch_load.md | 18 ++ docs/cmd/finch_login.md | 18 ++ docs/cmd/finch_logout.md | 15 ++ docs/cmd/finch_logs.md | 25 +++ docs/cmd/finch_network.md | 24 +++ docs/cmd/finch_pause.md | 15 ++ docs/cmd/finch_port.md | 15 ++ docs/cmd/finch_ps.md | 23 +++ docs/cmd/finch_pull.md | 26 +++ docs/cmd/finch_push.md | 27 +++ docs/cmd/finch_restart.md | 16 ++ docs/cmd/finch_rm.md | 17 ++ docs/cmd/finch_rmi.md | 17 ++ docs/cmd/finch_run.md | 98 ++++++++++ docs/cmd/finch_save.md | 18 ++ docs/cmd/finch_start.md | 17 ++ docs/cmd/finch_stats.md | 19 ++ docs/cmd/finch_stop.md | 16 ++ docs/cmd/finch_support-bundle_generate.md | 17 ++ docs/cmd/finch_system.md | 22 +++ docs/cmd/finch_tag.md | 15 ++ docs/cmd/finch_top.md | 15 ++ docs/cmd/finch_unpause.md | 15 ++ docs/cmd/finch_update.md | 28 +++ docs/cmd/finch_version.md | 15 ++ docs/cmd/finch_vm_init.md | 15 ++ docs/cmd/finch_vm_remove.md | 16 ++ docs/cmd/finch_vm_start.md | 15 ++ docs/cmd/finch_vm_status.md | 15 ++ docs/cmd/finch_vm_stop.md | 16 ++ docs/cmd/finch_volume.md | 24 +++ docs/cmd/finch_wait.md | 15 ++ pkg/system/stdlib.go | 8 + pkg/system/system.go | 10 + 58 files changed, 1538 insertions(+) create mode 100644 cmd/finch/doc.TEMPLATE.md create mode 100644 cmd/finch/gen_docs.go create mode 100644 docs/cmd/finch_build.md create mode 100644 docs/cmd/finch_builder.md create mode 100644 docs/cmd/finch_commit.md create mode 100644 docs/cmd/finch_completion_bash.md create mode 100644 docs/cmd/finch_completion_fish.md create mode 100644 docs/cmd/finch_completion_powershell.md create mode 100644 docs/cmd/finch_completion_zsh.md create mode 100644 docs/cmd/finch_compose.md create mode 100644 docs/cmd/finch_container.md create mode 100644 docs/cmd/finch_cp.md create mode 100644 docs/cmd/finch_create.md create mode 100644 docs/cmd/finch_events.md create mode 100644 docs/cmd/finch_exec.md create mode 100644 docs/cmd/finch_gen-docs_generate.md create mode 100644 docs/cmd/finch_help.md create mode 100644 docs/cmd/finch_history.md create mode 100644 docs/cmd/finch_image.md create mode 100644 docs/cmd/finch_images.md create mode 100644 docs/cmd/finch_info.md create mode 100644 docs/cmd/finch_inspect.md create mode 100644 docs/cmd/finch_kill.md create mode 100644 docs/cmd/finch_load.md create mode 100644 docs/cmd/finch_login.md create mode 100644 docs/cmd/finch_logout.md create mode 100644 docs/cmd/finch_logs.md create mode 100644 docs/cmd/finch_network.md create mode 100644 docs/cmd/finch_pause.md create mode 100644 docs/cmd/finch_port.md create mode 100644 docs/cmd/finch_ps.md create mode 100644 docs/cmd/finch_pull.md create mode 100644 docs/cmd/finch_push.md create mode 100644 docs/cmd/finch_restart.md create mode 100644 docs/cmd/finch_rm.md create mode 100644 docs/cmd/finch_rmi.md create mode 100644 docs/cmd/finch_run.md create mode 100644 docs/cmd/finch_save.md create mode 100644 docs/cmd/finch_start.md create mode 100644 docs/cmd/finch_stats.md create mode 100644 docs/cmd/finch_stop.md create mode 100644 docs/cmd/finch_support-bundle_generate.md create mode 100644 docs/cmd/finch_system.md create mode 100644 docs/cmd/finch_tag.md create mode 100644 docs/cmd/finch_top.md create mode 100644 docs/cmd/finch_unpause.md create mode 100644 docs/cmd/finch_update.md create mode 100644 docs/cmd/finch_version.md create mode 100644 docs/cmd/finch_vm_init.md create mode 100644 docs/cmd/finch_vm_remove.md create mode 100644 docs/cmd/finch_vm_start.md create mode 100644 docs/cmd/finch_vm_status.md create mode 100644 docs/cmd/finch_vm_stop.md create mode 100644 docs/cmd/finch_volume.md create mode 100644 docs/cmd/finch_wait.md diff --git a/cmd/finch/doc.TEMPLATE.md b/cmd/finch/doc.TEMPLATE.md new file mode 100644 index 000000000..c57ad5c16 --- /dev/null +++ b/cmd/finch/doc.TEMPLATE.md @@ -0,0 +1,36 @@ +--- +title: "{{ .CmdPath }}" +--- +## {{ .CmdPath }} + +{{ .Description }} + +{{if gt (len .Properties) 0}}### Properties +{{.Properties}} + +{{end}}``` +{{ .Usage }} +```{{if gt (len .Aliases) 0}} + +### Aliases +{{.Aliases}} +{{end}}{{if gt (len .Examples) 0}} + +### Examples +{{.Examples}} +{{end}}{{if gt (len .Commands) 0}} + +### Commands +``` +{{ .Commands }} +```{{end}}{{if gt (len .Options) 0}} + +### Options +``` +{{ .Options }} +```{{end}}{{if gt (len .SeeAlso) 0}} + +### SEE ALSO + +{{ .SeeAlso }} +{{end}} diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go new file mode 100644 index 000000000..e3d116814 --- /dev/null +++ b/cmd/finch/gen_docs.go @@ -0,0 +1,224 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +package main + +import ( + "bytes" + _ "embed" + "fmt" + "io" + "os" + "path/filepath" + "regexp" + "strings" + "text/template" + + "github.com/spf13/afero" + "github.com/spf13/cobra" + + "github.com/runfinch/finch/pkg/flog" + "github.com/runfinch/finch/pkg/system" +) + +// GenDocsSystemDeps contains the system dependencies for newGenDocsCommand. +// +//go:generate mockgen -copyright_file=../../copyright_header -destination=../../pkg/mocks/gen_docs_system_deps.go -package=mocks -mock_names GenDocsSystemDeps=GenDocsSystemDeps -source=gen_docs.go GenDocsSystemDeps +type GenDocsSystemDeps interface { + system.PipeGetter + system.StdoutGetter + system.StdoutSetter +} + +func newGenDocsCommand( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *cobra.Command { + genDocsCommand := &cobra.Command{ + Use: "gen-docs", + Short: "Document generation", + } + genDocsCommand.AddCommand( + newGenDocsGenerateCommand(rootCmd, logger, fs, deps), + ) + return genDocsCommand +} + +func newGenDocsGenerateCommand( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *cobra.Command { + genDocsGenerateCommand := &cobra.Command{ + Use: "generate", + Args: cobra.NoArgs, + Short: "Generate Finch docs", + RunE: newGenDocsGenerateAction(rootCmd, logger, fs, deps).runAdapter, + } + + genDocsGenerateCommand.Flags().StringP("path", "p", "", "Doc output directory") + // Ignore error since we check if the flag is set anyway + _ = genDocsGenerateCommand.MarkFlagRequired("path") + + return genDocsGenerateCommand +} + +type genDocsAction struct { + rootCmd *cobra.Command + logger flog.Logger + fs afero.Fs + deps GenDocsSystemDeps +} + +func newGenDocsGenerateAction( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *genDocsAction { + return &genDocsAction{ + rootCmd: rootCmd, + logger: logger, + deps: deps, + fs: fs, + } +} + +func (gd *genDocsAction) runAdapter(cmd *cobra.Command, _ []string) error { + path, err := cmd.Flags().GetString("path") + if err != nil { + return fmt.Errorf("failed to get required parameter 'path': %w", err) + } + return gd.run(path) +} + +func (gd *genDocsAction) run(outDir string) error { + return gd.captureHelpOutput(gd.rootCmd, outDir) +} + +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 + } + } + + if !cmd.Runnable() { + return nil + } + + gd.logger.Infof("Creating doc for command: %s", cmd.CommandPath()) + + baseName := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".md" + fileName := filepath.Clean(filepath.Join(outDir, baseName)) + f, err := gd.fs.OpenFile(fileName, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o666) + if err != nil { + return fmt.Errorf("error while creating out file %q: %w", fileName, err) + } + + // redirect Stdout to pipe + rescueStdout := gd.deps.Stdout() + r, w, _ := gd.deps.Pipe() + gd.deps.SetStdout(w) + + rootCmd := cmd.Root() + + // everything except the initial `finch` + args := strings.Split(cmd.CommandPath(), " ")[1:] + args = append(args, "--help") + rootCmd.SetArgs(args) + // rootCmd.SetOutput() would work for all "default finch" commands, but doesn't work + // for the nerdctl commands. Getting it to work would remove the need to capture all Stdout. + if err := rootCmd.Execute(); err != nil { + return fmt.Errorf("error while executing command (args=%v): %w", args, err) + } + gd.deps.SetStdout(rescueStdout) + + _ = w.Close() + helpText, err := io.ReadAll(r) + if err != nil { + return fmt.Errorf("error while reading stdout from pipe: %w", err) + } + + seeAlso := "" + if cmd.HasParent() && cmd.Parent().Runnable() { + parentName := cmd.Parent().CommandPath() + parentDocFile := parentName + ".md" + parentDocFile = strings.ReplaceAll(parentDocFile, " ", "_") + parentShortDescription := cmd.Parent().Short + seeAlso = fmt.Sprintf("* [%s](%s)\t - %s\n", parentName, parentDocFile, parentShortDescription) + } + + mdOut, err := convertToMarkdown(cmd.CommandPath(), seeAlso, string(helpText)) + if err != nil { + return fmt.Errorf("error while converting docs to markdown: %w", err) + } + + if _, err := f.WriteString(mdOut); err != nil { + return fmt.Errorf("error while writing docs to file (%q): %w", f.Name(), err) + } + + _ = f.Close() + + return nil +} + +//go:embed doc.TEMPLATE.md +var docTmpl string + +type docTmplOpts struct { + CmdPath string + Description string + Properties string + Usage string + Aliases string + Examples string + Commands string + Options string + SeeAlso string +} + +func convertToMarkdown(cmdPath, seeAlso, helpText string) (string, error) { + t := template.Must(template.New("docTmpl").Parse(docTmpl)) + opts := docTmplOpts{ + CmdPath: cmdPath, + } + + opts.SeeAlso = seeAlso + + // Assume that everything up until "header section" (i.e. `Usage:\n`) is a description + re := regexp.MustCompile(`(?msU)^(.*)[A-Z]\w*:\s`) + matches := re.FindStringSubmatch(helpText) + // Take the last index (if no match, 0 or if match, 1) as the description. + // This handles the rare case in where the only help info is a description. + opts.Description = strings.TrimSpace(matches[len(matches)-1]) + + // The rest of the fields are treated as optional. + // A reference of all fields and how they may appear in help out put can + // be found here: https://github.com/spf13/cobra/blob/v1.7.0/command.go#L539-L568 + opts.Properties = tryExtractField(helpText, "Properties") + opts.Usage = tryExtractField(helpText, "Usage") + opts.Aliases = tryExtractField(helpText, "Aliases") + opts.Examples = tryExtractField(helpText, "Examples") + opts.Commands = tryExtractField(helpText, "Commands") + opts.Options = tryExtractField(helpText, "Flags") + + var tmpl bytes.Buffer + if err := t.Execute(&tmpl, opts); err != nil { + return "", err + } + + return tmpl.String(), nil +} + +func tryExtractField(helpString, fieldName string) string { + re := regexp.MustCompile(fmt.Sprintf(`(?smU)^%s:\s(.*)^\s?$`, fieldName)) + matches := re.FindStringSubmatch(strings.TrimSpace(helpString)) + if len(matches) == 2 { + return strings.TrimSuffix(strings.TrimSuffix(matches[1], " "), "\n") + } + return "" +} diff --git a/cmd/finch/main.go b/cmd/finch/main.go index 1c95ca958..57d6079a7 100644 --- a/cmd/finch/main.go +++ b/cmd/finch/main.go @@ -107,6 +107,7 @@ var newApp = func(logger flog.Logger, fp path.Finch, fs afero.Fs, fc *config.Fin newVersionCommand(lcc, logger, stdOut), virtualMachineCommands(logger, fp, lcc, ecc, fs, fc), newSupportBundleCommand(logger, supportBundleBuilder, lcc), + newGenDocsCommand(rootCmd, logger, fs, system.NewStdLib()), ) rootCmd.AddCommand(allCommands...) diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md new file mode 100644 index 000000000..101c06dd9 --- /dev/null +++ b/docs/cmd/finch_build.md @@ -0,0 +1,34 @@ +--- +title: "finch build" +--- +## finch build + +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. + +``` +finch build [flags] PATH +``` + +### Options +``` + --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) + --cache-to stringArray Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) + -f, --file string Name of the Dockerfile + -h, --help help for build + --iidfile string Write the image ID to the file + --label stringArray Set metadata for an image + --network string Set type of network for build (format:network=default|none|host) (default "default") + --no-cache Do not use cache when building the image + -o, --output string Output destination (format: type=local,dest=path) + --platform strings Set target platform for build (e.g., "amd64", "arm64") + --progress string Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto") + -q, --quiet Suppress the build output and print image ID on success + --rm Remove intermediate containers after a successful build (default true) + --secret stringArray Secret file to expose to the build: id=mysecret,src=/local/secret + --ssh stringArray SSH agent socket or keys to expose to the build (format: default|[=|[,]]) + -t, --tag stringArray Name and optionally a tag in the 'name:tag' format + --target string Set the target build stage to build +``` diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md new file mode 100644 index 000000000..3dddea16e --- /dev/null +++ b/docs/cmd/finch_builder.md @@ -0,0 +1,22 @@ +--- +title: "finch builder" +--- +## finch builder + +Manage builds + +``` +finch builder [flags] +``` + +### Commands +``` + build Build an image from a Dockerfile. Needs buildkitd to be running. + debug Debug Dockerfile + prune Clean up BuildKit build cache +``` + +### Options +``` + -h, --help help for builder +``` diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md new file mode 100644 index 000000000..4e889d4a2 --- /dev/null +++ b/docs/cmd/finch_commit.md @@ -0,0 +1,19 @@ +--- +title: "finch commit" +--- +## finch commit + +Create a new image from a container's changes + +``` +finch commit [flags] CONTAINER REPOSITORY[:TAG] +``` + +### Options +``` + -a, --author string Author (e.g., "finch contributor ") + -c, --change stringArray Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) + -h, --help help for commit + -m, --message string Commit message + -p, --pause Pause container during commit (default true) +``` diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md new file mode 100644 index 000000000..f6d75eacb --- /dev/null +++ b/docs/cmd/finch_completion_bash.md @@ -0,0 +1,27 @@ +--- +title: "finch completion bash" +--- +## finch completion bash + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(finch completion bash) + +To load completions for every new session, execute once: + +#### + +``` + finch completion bash +``` + +### Options +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md new file mode 100644 index 000000000..854c0481b --- /dev/null +++ b/docs/cmd/finch_completion_fish.md @@ -0,0 +1,26 @@ +--- +title: "finch completion fish" +--- +## finch completion fish + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + finch completion fish | source + +To load completions for every new session, execute once: + + finch completion fish > ~/.config/fish/completions/finch.fish + +You will need to start a new shell for this setup to take effect. + +``` + finch completion fish [flags] +``` + +### Options +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md new file mode 100644 index 000000000..e28138b28 --- /dev/null +++ b/docs/cmd/finch_completion_powershell.md @@ -0,0 +1,23 @@ +--- +title: "finch completion powershell" +--- +## finch completion powershell + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + finch completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + +``` + finch completion powershell [flags] +``` + +### Options +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md new file mode 100644 index 000000000..d1dd6e4d1 --- /dev/null +++ b/docs/cmd/finch_completion_zsh.md @@ -0,0 +1,29 @@ +--- +title: "finch completion zsh" +--- +## finch completion zsh + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(finch completion zsh) + +To load completions for every new session, execute once: + +#### + +``` + finch completion zsh [flags] +``` + +### Options +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md new file mode 100644 index 000000000..9a4eefd1e --- /dev/null +++ b/docs/cmd/finch_compose.md @@ -0,0 +1,49 @@ +--- +title: "finch compose" +--- +## finch compose + +Compose + +``` +finch compose [flags] COMMAND +``` + +### Commands +``` + build Build or rebuild services + config Validate and view the Compose file + cp Copy files/folders between a service container and the local filesystem + create Creates containers for one or more services + down Remove containers and associated resources + exec Execute a command in a running container of the service + images List images used by created containers in services + kill Force stop service containers + logs Show logs of running containers + pause Pause all processes within containers of service(s). They can be unpaused with finch compose unpause + port Print the public port for a port binding + ps List containers of services + pull Pull service images + push Push service images + restart Restart containers of given (or all) services + rm Remove stopped service containers + run Run a one-off command on a service + start Start existing containers for service(s) + stop Stop running containers without removing them. + top Display the running processes of service containers + unpause Unpause all processes within containers of service(s). + up Create and start containers + version Show the Compose version information +``` + +### Options +``` + --env-file string Specify an alternate environment file + -f, --f stringArray Alias of --file + --file stringArray Specify an alternate compose file + -h, --help help for compose + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --profile stringArray Specify a profile to enable + --project-directory string Specify an alternate working directory + -p, --project-name string Specify an alternate project name +``` diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md new file mode 100644 index 000000000..bee0536da --- /dev/null +++ b/docs/cmd/finch_container.md @@ -0,0 +1,41 @@ +--- +title: "finch container" +--- +## finch container + +Manage containers + +``` +finch container [flags] +``` + +### Commands +``` + 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. + create Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + exec Run a command in a running container + inspect Display detailed information on one or more containers. + kill Kill one or more running containers + logs Fetch the logs of a container. Expected to be used with 'finch run -d'. + ls List containers + pause Pause all processes within one or more containers + port List port mappings or a specific mapping for the container + prune Remove all stopped containers + rename rename a container + restart Restart one or more running containers + rm Remove one or more containers + run Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + start Start one or more running containers + stats Display a live stream of container(s) resource usage statistics. + stop Stop one or more running containers + unpause Unpause all processes within one or more containers + update Update one or more running containers + wait Block until one or more containers stop, then print their exit codes. +``` + +### Options +``` + -h, --help help for container +``` diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md new file mode 100644 index 000000000..10dd823dc --- /dev/null +++ b/docs/cmd/finch_cp.md @@ -0,0 +1,20 @@ +--- +title: "finch cp" +--- +## finch cp + +Copy files/folders between a running container and the local filesystem. +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'. + +``` +finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|- + finch cp [flags] SRC_PATH|- CONTAINER:DEST_PATH +``` + +### Options +``` + -L, --follow-link Always follow symbolic link in SRC_PATH. + -h, --help help for cp +``` diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md new file mode 100644 index 000000000..9c0fd2585 --- /dev/null +++ b/docs/cmd/finch_create.md @@ -0,0 +1,97 @@ +--- +title: "finch create" +--- +## finch create + +Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +``` +finch create [flags] IMAGE [COMMAND] [ARG...] +``` + +### Options +``` + --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 + --cap-drop strings Drop Linux capabilities + --cgroup-conf strings Configure cgroup v2 (key=value) + --cgroup-parent string Optional parent cgroup for the container + --cgroupns string Cgroup namespace to use, the default depends on the cgroup version ("host"|"private") (default "private") + --cidfile string Write the container ID to the file + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + --device strings Add a host device to the container + --dns strings Set custom DNS servers + --dns-opt strings Set DNS options + --dns-option strings Set DNS options + --dns-search strings Set custom DNS search domains + --entrypoint stringArray Overwrite the default ENTRYPOINT of the image + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + --gpus stringArray GPU devices to add to the container ('all' to pass all GPUs) + --group-add strings Add additional groups to join + --help show help + -h, --hostname string Container host name + --init Run an init process inside the container, Default to use tini + --init-binary string The custom binary to use as the init process (default "tini") + -i, --interactive Keep STDIN open even if not attached + --ip string IPv4 address to assign to the container + --ipc string IPC namespace to use ("host"|"private") + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --isolation string Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default (default "default") + --kernel-memory string Kernel memory limit (deprecated) + -l, --label stringArray Set metadata on container + --label-file strings Set metadata on container from file + --log-driver string Logging driver for the container. Default is json-file. It also supports logURI (eg: --log-driver binary://) (default "json-file") + --log-opt stringArray Log driver options + --mac-address string MAC address to assign to the container + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --memory-swappiness int Tune container memory swappiness (0 to 100) (default -1) (default -1) + --mount stringArray Attach a filesystem mount to the container + --name string Assign a name to the container + --net strings Connect a container to a network ("bridge"|"host"|"none"|) (default [bridge]) + --network strings Connect a container to a network ("bridge"|"host"|"none"|"container:"|) (default [bridge]) + --oom-kill-disable Disable OOM Killer + --oom-score-adj int Tune container’s OOM preferences (-1000 to 1000, rootless: 100 to 1000) + --pid string PID namespace to use + --pidfile string file path to write the task's pid + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --platform string Set platform (e.g. "amd64", "arm64") + --privileged Give extended privileges to this container + -p, --publish strings Publish a container's port(s) to the host + --pull string Pull image before running ("always"|"missing"|"never") (default "missing") + --rdt-class string Name of the RDT class (or CLOS) to associate the container with + --read-only Mount the container's root filesystem as read only + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") + --rm Automatically remove the container when it exits + --rootfs The first argument is not an image but the rootfs to the exploded container + --runtime string Runtime to use for this container, e.g. "crun", or "io.containerd.runsc.v1" (default "io.containerd.runc.v2") + --security-opt stringArray Security options + --shm-size string Size of /dev/shm + --stop-signal string Signal to stop a container (default "SIGTERM") + --stop-timeout int Timeout (in seconds) to stop a container + --sysctl stringArray Sysctl options + --tmpfs stringArray Mount a tmpfs directory + -t, --tty Allocate a pseudo-TTY + --ulimit strings Ulimit options + --umask string Set the umask inside the container. Defaults to 0022 + -u, --user string Username or UID (format: [:]) + --uts string UTS namespace to use + --verify string Verify the image (none|cosign|notation) (default "none") + -v, --volume stringArray Bind mount a volume + --volumes-from stringArray Mount volumes from the specified container(s) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md new file mode 100644 index 000000000..d4df03517 --- /dev/null +++ b/docs/cmd/finch_events.md @@ -0,0 +1,16 @@ +--- +title: "finch events" +--- +## finch events + +Get real time events from the server + +``` +finch events [flags] +``` + +### Options +``` + --format string Format the output using the given Go template, e.g, '{{json .}}' + -h, --help help for events +``` diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md new file mode 100644 index 000000000..970d53582 --- /dev/null +++ b/docs/cmd/finch_exec.md @@ -0,0 +1,23 @@ +--- +title: "finch exec" +--- +## finch exec + +Run a command in a running container + +``` +finch exec [flags] CONTAINER COMMAND [ARG...] +``` + +### Options +``` + -d, --detach Detached mode: run command in the background + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + -h, --help help for exec + -i, --interactive Keep STDIN open even if not attached + --privileged Give extended privileges to the command + -t, --tty Allocate a pseudo-TTY + -u, --user string Username or UID (format: [:]) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_gen-docs_generate.md b/docs/cmd/finch_gen-docs_generate.md new file mode 100644 index 000000000..d288bacd7 --- /dev/null +++ b/docs/cmd/finch_gen-docs_generate.md @@ -0,0 +1,16 @@ +--- +title: "finch gen-docs generate" +--- +## finch gen-docs generate + +Generate Finch docs + +``` + finch gen-docs generate [flags] +``` + +### Options +``` + -h, --help help for generate + -p, --path string Doc output directory +``` diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md new file mode 100644 index 000000000..f5c2eab8b --- /dev/null +++ b/docs/cmd/finch_help.md @@ -0,0 +1,16 @@ +--- +title: "finch help" +--- +## finch help + +Help provides help for any command in the application. +Simply type finch help [path to command] for full details. + +``` + finch help [command] [flags] +``` + +### Options +``` + -h, --help help for help +``` diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md new file mode 100644 index 000000000..cbef21d69 --- /dev/null +++ b/docs/cmd/finch_history.md @@ -0,0 +1,18 @@ +--- +title: "finch history" +--- +## finch history + +Show the history of an image + +``` +finch history [flags] IMAGE +``` + +### Options +``` + -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 + -q, --quiet Only show numeric IDs +``` diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md new file mode 100644 index 000000000..932c6bde4 --- /dev/null +++ b/docs/cmd/finch_image.md @@ -0,0 +1,33 @@ +--- +title: "finch image" +--- +## finch image + +Manage images + +``` +finch image [flags] +``` + +### Commands +``` + build Build an image from a Dockerfile. Needs buildkitd to be running. + convert convert an image + decrypt decrypt an image + encrypt encrypt image layers + history Show the history of an image + inspect Display detailed information on one or more images. + load Load an image from a tar archive or STDIN + ls List images + prune Remove unused images + pull Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + push Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. + rm Remove one or more images + save Save one or more images to a tar archive (streamed to STDOUT by default) + tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE +``` + +### Options +``` + -h, --help help for image +``` diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md new file mode 100644 index 000000000..3a11e68d1 --- /dev/null +++ b/docs/cmd/finch_images.md @@ -0,0 +1,32 @@ +--- +title: "finch images" +--- +## finch images + +List images + +### Properties +- REPOSITORY: Repository +- TAG: Tag +- NAME: Name of the image, --names for skip parsing as repository and tag. +- IMAGE ID: OCI Digest. Usually different from Docker image ID. Shared for multi-platform images. +- CREATED: Created time +- PLATFORM: Platform +- SIZE: Size of the unpacked snapshots +- BLOB SIZE: Size of the blobs (such as layer tarballs) in the content store + +``` +finch images [flags] [REPOSITORY[:TAG]] +``` + +### Options +``` + -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 + --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' + -h, --help help for images + --names Show image names + --no-trunc Don't truncate output + -q, --quiet Only show numeric IDs +``` diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md new file mode 100644 index 000000000..1d4dab6aa --- /dev/null +++ b/docs/cmd/finch_info.md @@ -0,0 +1,17 @@ +--- +title: "finch info" +--- +## finch info + +Display system-wide information + +``` +finch info [flags] +``` + +### Options +``` + -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") +``` diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md new file mode 100644 index 000000000..40cf06a28 --- /dev/null +++ b/docs/cmd/finch_inspect.md @@ -0,0 +1,18 @@ +--- +title: "finch inspect" +--- +## finch inspect + +Return low-level information on objects. + +``` +finch inspect [flags] +``` + +### Options +``` + -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") + --type string Return JSON for specified type +``` diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md new file mode 100644 index 000000000..82345fff7 --- /dev/null +++ b/docs/cmd/finch_kill.md @@ -0,0 +1,16 @@ +--- +title: "finch kill" +--- +## finch kill + +Kill one or more running containers + +``` +finch kill [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for kill + -s, --signal string Signal to send to the container (default "KILL") +``` diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md new file mode 100644 index 000000000..fe044d04b --- /dev/null +++ b/docs/cmd/finch_load.md @@ -0,0 +1,18 @@ +--- +title: "finch load" +--- +## finch load + +Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. + +``` +finch load [flags] +``` + +### Options +``` + --all-platforms Import content for all platforms + -h, --help help for load + -i, --input string Read from tar archive file, instead of STDIN + --platform strings Import content for a specific platform +``` diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md new file mode 100644 index 000000000..0ec907e76 --- /dev/null +++ b/docs/cmd/finch_login.md @@ -0,0 +1,18 @@ +--- +title: "finch login" +--- +## finch login + +Log in to a container registry + +``` +finch login [flags] [SERVER] +``` + +### Options +``` + -h, --help help for login + -p, --password string Password + --password-stdin Take the password from stdin + -u, --username string Username +``` diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md new file mode 100644 index 000000000..6e6ccafd5 --- /dev/null +++ b/docs/cmd/finch_logout.md @@ -0,0 +1,15 @@ +--- +title: "finch logout" +--- +## finch logout + +Log out from a container registry + +``` +finch logout [flags] [SERVER] +``` + +### Options +``` + -h, --help help for logout +``` diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md new file mode 100644 index 000000000..a31275353 --- /dev/null +++ b/docs/cmd/finch_logs.md @@ -0,0 +1,25 @@ +--- +title: "finch logs" +--- +## finch logs + +Fetch the logs of a container. + +The following containers are supported: +- Containers created with 'finch run -d'. The log is currently empty for containers created without '-d'. +- Containers created with 'finch compose'. +- Containers created with Kubernetes (EXPERIMENTAL). + +``` +finch logs [flags] CONTAINER +``` + +### Options +``` + -f, --follow Follow log output + -h, --help help for logs + --since string Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) + -n, --tail string Number of lines to show from the end of the logs (default "all") + -t, --timestamps Show timestamps + --until string Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) +``` diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md new file mode 100644 index 000000000..1a3d04670 --- /dev/null +++ b/docs/cmd/finch_network.md @@ -0,0 +1,24 @@ +--- +title: "finch network" +--- +## finch network + +Manage networks + +``` +finch network [flags] +``` + +### Commands +``` + create Create a network + inspect Display detailed information on one or more networks + ls List networks + prune Remove all unused networks + rm Remove one or more networks +``` + +### Options +``` + -h, --help help for network +``` diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md new file mode 100644 index 000000000..518bd72bc --- /dev/null +++ b/docs/cmd/finch_pause.md @@ -0,0 +1,15 @@ +--- +title: "finch pause" +--- +## finch pause + +Pause all processes within one or more containers + +``` +finch pause [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for pause +``` diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md new file mode 100644 index 000000000..7011764ac --- /dev/null +++ b/docs/cmd/finch_port.md @@ -0,0 +1,15 @@ +--- +title: "finch port" +--- +## finch port + +List port mappings or a specific mapping for the container + +``` +finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] +``` + +### Options +``` + -h, --help help for port +``` diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md new file mode 100644 index 000000000..2fbfe2414 --- /dev/null +++ b/docs/cmd/finch_ps.md @@ -0,0 +1,23 @@ +--- +title: "finch ps" +--- +## finch ps + +List containers + +``` +finch ps [flags] +``` + +### Options +``` + -a, --all Show all containers (default shows just running) + -f, --filter strings Filter matches containers based on given conditions + --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' + -h, --help help for ps + -n, --last int Show n last created containers (includes all states) (default -1) + -l, --latest Show the latest created container (includes all states) + --no-trunc Don't truncate output + -q, --quiet Only display container IDs + -s, --size Display total file sizes +``` diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md new file mode 100644 index 000000000..9a66b87f1 --- /dev/null +++ b/docs/cmd/finch_pull.md @@ -0,0 +1,26 @@ +--- +title: "finch pull" +--- +## finch pull + +Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +``` +finch pull [flags] NAME[:TAG] +``` + +### Options +``` + --all-platforms Pull content for all platforms + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign,, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign,. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + -h, --help help for pull + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --platform strings Pull content for a specific platform + -q, --quiet Suppress verbose output + --unpack string Unpack the image for the current single platform (auto/true/false) (default "auto") + --verify string Verify the image (none|cosign|notation) (default "none") +``` diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md new file mode 100644 index 000000000..75736c20d --- /dev/null +++ b/docs/cmd/finch_push.md @@ -0,0 +1,27 @@ +--- +title: "finch push" +--- +## finch push + +Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. + +``` +finch push [flags] NAME[:TAG] +``` + +### Options +``` + --all-platforms Push content for all platforms + --allow-nondistributable-artifacts Allow pushing images with non-distributable blobs + --cosign-key string Path to the private key file, KMS URI or Kubernetes Secret for --sign=cosign + --estargz Convert the image into eStargz + -h, --help help for push + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --ipfs-ensure-image Ensure the entire contents of the image is locally available before push (default true) + --notation-key-name string Signing key name for a key previously added to notation's key list for --sign=notation + --platform strings Push content for a specific platform + -q, --quiet Suppress verbose output + --sign string Sign the image (none|cosign|notation (default "none") + --soci-min-layer-size int Minimum layer size to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10 MiB. (default -1) + --soci-span-size int Span size that soci index uses to segment layer data. Default is 4 MiB. (default -1) +``` diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md new file mode 100644 index 000000000..ccd69ebda --- /dev/null +++ b/docs/cmd/finch_restart.md @@ -0,0 +1,16 @@ +--- +title: "finch restart" +--- +## finch restart + +Restart one or more running containers + +``` +finch restart [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for restart + -t, --time uint Seconds to wait for stop before killing it (default 10) +``` diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md new file mode 100644 index 000000000..0bfb91589 --- /dev/null +++ b/docs/cmd/finch_rm.md @@ -0,0 +1,17 @@ +--- +title: "finch rm" +--- +## finch rm + +Remove one or more containers + +``` +finch rm [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) + -h, --help help for rm + -v, --volumes Remove volumes associated with the container +``` diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md new file mode 100644 index 000000000..a48a0a07e --- /dev/null +++ b/docs/cmd/finch_rmi.md @@ -0,0 +1,17 @@ +--- +title: "finch rmi" +--- +## finch rmi + +Remove one or more images + +``` +finch rmi [flags] IMAGE [IMAGE, ...] +``` + +### Options +``` + --async Asynchronous mode + -f, --force Force removal of the image + -h, --help help for rmi +``` diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md new file mode 100644 index 000000000..15f1570a3 --- /dev/null +++ b/docs/cmd/finch_run.md @@ -0,0 +1,98 @@ +--- +title: "finch run" +--- +## finch run + +Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +``` +finch run [flags] IMAGE [COMMAND] [ARG...] +``` + +### Options +``` + --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 + --cap-drop strings Drop Linux capabilities + --cgroup-conf strings Configure cgroup v2 (key=value) + --cgroup-parent string Optional parent cgroup for the container + --cgroupns string Cgroup namespace to use, the default depends on the cgroup version ("host"|"private") (default "private") + --cidfile string Write the container ID to the file + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + -d, --detach Run container in background and print container ID + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + --device strings Add a host device to the container + --dns strings Set custom DNS servers + --dns-opt strings Set DNS options + --dns-option strings Set DNS options + --dns-search strings Set custom DNS search domains + --entrypoint stringArray Overwrite the default ENTRYPOINT of the image + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + --gpus stringArray GPU devices to add to the container ('all' to pass all GPUs) + --group-add strings Add additional groups to join + --help show help + -h, --hostname string Container host name + --init Run an init process inside the container, Default to use tini + --init-binary string The custom binary to use as the init process (default "tini") + -i, --interactive Keep STDIN open even if not attached + --ip string IPv4 address to assign to the container + --ipc string IPC namespace to use ("host"|"private") + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --isolation string Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default (default "default") + --kernel-memory string Kernel memory limit (deprecated) + -l, --label stringArray Set metadata on container + --label-file strings Set metadata on container from file + --log-driver string Logging driver for the container. Default is json-file. It also supports logURI (eg: --log-driver binary://) (default "json-file") + --log-opt stringArray Log driver options + --mac-address string MAC address to assign to the container + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --memory-swappiness int Tune container memory swappiness (0 to 100) (default -1) (default -1) + --mount stringArray Attach a filesystem mount to the container + --name string Assign a name to the container + --net strings Connect a container to a network ("bridge"|"host"|"none"|) (default [bridge]) + --network strings Connect a container to a network ("bridge"|"host"|"none"|"container:"|) (default [bridge]) + --oom-kill-disable Disable OOM Killer + --oom-score-adj int Tune container’s OOM preferences (-1000 to 1000, rootless: 100 to 1000) + --pid string PID namespace to use + --pidfile string file path to write the task's pid + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --platform string Set platform (e.g. "amd64", "arm64") + --privileged Give extended privileges to this container + -p, --publish strings Publish a container's port(s) to the host + --pull string Pull image before running ("always"|"missing"|"never") (default "missing") + --rdt-class string Name of the RDT class (or CLOS) to associate the container with + --read-only Mount the container's root filesystem as read only + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") + --rm Automatically remove the container when it exits + --rootfs The first argument is not an image but the rootfs to the exploded container + --runtime string Runtime to use for this container, e.g. "crun", or "io.containerd.runsc.v1" (default "io.containerd.runc.v2") + --security-opt stringArray Security options + --shm-size string Size of /dev/shm + --stop-signal string Signal to stop a container (default "SIGTERM") + --stop-timeout int Timeout (in seconds) to stop a container + --sysctl stringArray Sysctl options + --tmpfs stringArray Mount a tmpfs directory + -t, --tty Allocate a pseudo-TTY + --ulimit strings Ulimit options + --umask string Set the umask inside the container. Defaults to 0022 + -u, --user string Username or UID (format: [:]) + --uts string UTS namespace to use + --verify string Verify the image (none|cosign|notation) (default "none") + -v, --volume stringArray Bind mount a volume + --volumes-from stringArray Mount volumes from the specified container(s) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md new file mode 100644 index 000000000..d9af9af84 --- /dev/null +++ b/docs/cmd/finch_save.md @@ -0,0 +1,18 @@ +--- +title: "finch save" +--- +## finch save + +The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. + +``` +finch save [flags] +``` + +### Options +``` + --all-platforms Export content for all platforms + -h, --help help for save + -o, --output string Write to a file, instead of STDOUT + --platform strings Export content for a specific platform +``` diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md new file mode 100644 index 000000000..fe9fe15fd --- /dev/null +++ b/docs/cmd/finch_start.md @@ -0,0 +1,17 @@ +--- +title: "finch start" +--- +## finch start + +Start one or more running containers + +``` +finch start [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -a, --attach Attach STDOUT/STDERR and forward signals + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + -h, --help help for start +``` diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md new file mode 100644 index 000000000..9d6b47c5a --- /dev/null +++ b/docs/cmd/finch_stats.md @@ -0,0 +1,19 @@ +--- +title: "finch stats" +--- +## finch stats + +Display a live stream of container(s) resource usage statistics. + +``` +finch stats [flags] +``` + +### Options +``` + -a, --all Show all containers (default shows just running) + --format string Pretty-print images using a Go template, e.g, '{{json .}}' + -h, --help help for stats + --no-stream Disable streaming stats and only pull the first result + --no-trunc Do not truncate output +``` diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md new file mode 100644 index 000000000..9c9bb119a --- /dev/null +++ b/docs/cmd/finch_stop.md @@ -0,0 +1,16 @@ +--- +title: "finch stop" +--- +## finch stop + +Stop one or more running containers + +``` +finch stop [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for stop + -t, --time int Seconds to wait before sending a SIGKILL (default 10) +``` diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md new file mode 100644 index 000000000..f4470e8fb --- /dev/null +++ b/docs/cmd/finch_support-bundle_generate.md @@ -0,0 +1,17 @@ +--- +title: "finch support-bundle generate" +--- +## finch support-bundle generate + +Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. + +``` + finch support-bundle generate [flags] +``` + +### Options +``` + --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded + -h, --help help for generate + --include stringArray additional files to include in the support bundle, specified by absolute or relative path. to include a file from the VM, prefix the file path with "vm:" +``` diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md new file mode 100644 index 000000000..e9ef646ea --- /dev/null +++ b/docs/cmd/finch_system.md @@ -0,0 +1,22 @@ +--- +title: "finch system" +--- +## finch system + +Manage containerd + +``` +finch system [flags] +``` + +### Commands +``` + events Get real time events from the server + info Display system-wide information + prune Remove unused data +``` + +### Options +``` + -h, --help help for system +``` diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md new file mode 100644 index 000000000..81e4f347f --- /dev/null +++ b/docs/cmd/finch_tag.md @@ -0,0 +1,15 @@ +--- +title: "finch tag" +--- +## finch tag + +Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE + +``` +finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] +``` + +### Options +``` + -h, --help help for tag +``` diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md new file mode 100644 index 000000000..cddf61bf6 --- /dev/null +++ b/docs/cmd/finch_top.md @@ -0,0 +1,15 @@ +--- +title: "finch top" +--- +## finch top + +Display the running processes of a container + +``` +finch top CONTAINER [ps OPTIONS] [flags] +``` + +### Options +``` + -h, --help help for top +``` diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md new file mode 100644 index 000000000..e3d9b1382 --- /dev/null +++ b/docs/cmd/finch_unpause.md @@ -0,0 +1,15 @@ +--- +title: "finch unpause" +--- +## finch unpause + +Unpause all processes within one or more containers + +``` +finch unpause [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for unpause +``` diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md new file mode 100644 index 000000000..b13427b97 --- /dev/null +++ b/docs/cmd/finch_update.md @@ -0,0 +1,28 @@ +--- +title: "finch update" +--- +## finch update + +Update one or more running containers + +``` +finch update [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + -h, --help help for update + --kernel-memory string Kernel memory limit (deprecated) + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") +``` diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md new file mode 100644 index 000000000..7261a8605 --- /dev/null +++ b/docs/cmd/finch_version.md @@ -0,0 +1,15 @@ +--- +title: "finch version" +--- +## finch version + +Shows Finch version information + +``` + finch version [flags] +``` + +### Options +``` + -h, --help help for version +``` diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md new file mode 100644 index 000000000..232141d72 --- /dev/null +++ b/docs/cmd/finch_vm_init.md @@ -0,0 +1,15 @@ +--- +title: "finch vm init" +--- +## finch vm init + +Initialize the virtual machine + +``` + finch vm init [flags] +``` + +### Options +``` + -h, --help help for init +``` diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md new file mode 100644 index 000000000..8ee73973f --- /dev/null +++ b/docs/cmd/finch_vm_remove.md @@ -0,0 +1,16 @@ +--- +title: "finch vm remove" +--- +## finch vm remove + +Remove the virtual machine instance + +``` + finch vm remove [flags] +``` + +### Options +``` + -f, --force forcibly remove finch VM + -h, --help help for remove +``` diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md new file mode 100644 index 000000000..dcf3a6ea6 --- /dev/null +++ b/docs/cmd/finch_vm_start.md @@ -0,0 +1,15 @@ +--- +title: "finch vm start" +--- +## finch vm start + +Start the virtual machine + +``` + finch vm start [flags] +``` + +### Options +``` + -h, --help help for start +``` diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md new file mode 100644 index 000000000..342c4b46a --- /dev/null +++ b/docs/cmd/finch_vm_status.md @@ -0,0 +1,15 @@ +--- +title: "finch vm status" +--- +## finch vm status + +Status of the virtual machine + +``` + finch vm status [flags] +``` + +### Options +``` + -h, --help help for status +``` diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md new file mode 100644 index 000000000..1722e968f --- /dev/null +++ b/docs/cmd/finch_vm_stop.md @@ -0,0 +1,16 @@ +--- +title: "finch vm stop" +--- +## finch vm stop + +Stop the virtual machine + +``` + finch vm stop [flags] +``` + +### Options +``` + -f, --force forcibly stop finch VM + -h, --help help for stop +``` diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md new file mode 100644 index 000000000..0734da547 --- /dev/null +++ b/docs/cmd/finch_volume.md @@ -0,0 +1,24 @@ +--- +title: "finch volume" +--- +## finch volume + +Manage volumes + +``` +finch volume [flags] +``` + +### Commands +``` + create Create a volume + inspect Display detailed information on one or more volumes + ls List volumes + prune Remove all unused local volumes + rm Remove one or more volumes +``` + +### Options +``` + -h, --help help for volume +``` diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md new file mode 100644 index 000000000..705746ef1 --- /dev/null +++ b/docs/cmd/finch_wait.md @@ -0,0 +1,15 @@ +--- +title: "finch wait" +--- +## finch wait + +Block until one or more containers stop, then print their exit codes. + +``` +finch wait [flags] CONTAINER [CONTAINER, ...] +``` + +### Options +``` + -h, --help help for wait +``` diff --git a/pkg/system/stdlib.go b/pkg/system/stdlib.go index dc2102971..33b29eb64 100644 --- a/pkg/system/stdlib.go +++ b/pkg/system/stdlib.go @@ -42,6 +42,10 @@ func (s *StdLib) LookupEnv(key string) (string, bool) { return os.LookupEnv(key) } +func (s *StdLib) Pipe() (*os.File, *os.File, error) { + return os.Pipe() +} + func (s *StdLib) Stdin() *os.File { return os.Stdin } @@ -50,6 +54,10 @@ func (s *StdLib) Stdout() *os.File { return os.Stdout } +func (s *StdLib) SetStdout(w *os.File) { + os.Stdout = w +} + func (s *StdLib) Stderr() *os.File { return os.Stderr } diff --git a/pkg/system/system.go b/pkg/system/system.go index 9c589b4da..8143f88c8 100644 --- a/pkg/system/system.go +++ b/pkg/system/system.go @@ -52,6 +52,11 @@ type EnvChecker interface { LookupEnv(key string) (string, bool) } +// PipeGetter mocks out os.Pipe. +type PipeGetter interface { + Pipe() (*os.File, *os.File, error) +} + // StdinGetter mocks out os.Stdin. type StdinGetter interface { Stdin() *os.File @@ -62,6 +67,11 @@ type StdoutGetter interface { Stdout() *os.File } +// StdoutSetter mocks out redirecting os.Stdout. +type StdoutSetter interface { + SetStdout(*os.File) +} + // StderrGetter mocks out os.Stderr. type StderrGetter interface { Stderr() *os.File From 78790d1af443929eb93e259e35b1d5dcecc18ac8 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Thu, 19 Oct 2023 12:14:41 -0400 Subject: [PATCH 02/11] mark gen-docs generate as hidden Signed-off-by: Justin Alvarez --- cmd/finch/gen_docs.go | 11 ++++++----- docs/cmd/finch_gen-docs_generate.md | 16 ---------------- 2 files changed, 6 insertions(+), 21 deletions(-) delete mode 100644 docs/cmd/finch_gen-docs_generate.md diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go index e3d116814..16674c18a 100644 --- a/cmd/finch/gen_docs.go +++ b/cmd/finch/gen_docs.go @@ -53,10 +53,11 @@ func newGenDocsGenerateCommand( deps GenDocsSystemDeps, ) *cobra.Command { genDocsGenerateCommand := &cobra.Command{ - Use: "generate", - Args: cobra.NoArgs, - Short: "Generate Finch docs", - RunE: newGenDocsGenerateAction(rootCmd, logger, fs, deps).runAdapter, + Use: "generate", + Args: cobra.NoArgs, + Hidden: true, + Short: "Generate Finch docs", + RunE: newGenDocsGenerateAction(rootCmd, logger, fs, deps).runAdapter, } genDocsGenerateCommand.Flags().StringP("path", "p", "", "Doc output directory") @@ -106,7 +107,7 @@ func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) er } } - if !cmd.Runnable() { + if !cmd.Runnable() || cmd.Hidden { return nil } diff --git a/docs/cmd/finch_gen-docs_generate.md b/docs/cmd/finch_gen-docs_generate.md deleted file mode 100644 index d288bacd7..000000000 --- a/docs/cmd/finch_gen-docs_generate.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "finch gen-docs generate" ---- -## finch gen-docs generate - -Generate Finch docs - -``` - finch gen-docs generate [flags] -``` - -### Options -``` - -h, --help help for generate - -p, --path string Doc output directory -``` From 661c93ca164a34732f7995cd83ab3ddb4b11bbdc Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 12:36:29 -0400 Subject: [PATCH 03/11] add unit tests Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE.md | 5 +- cmd/finch/gen_docs.go | 8 +- cmd/finch/gen_docs_test.go | 183 ++++++++++++++++++++++++++++++ cmd/finch/main_test.go | 2 +- pkg/mocks/gen_docs_system_deps.go | 80 +++++++++++++ 5 files changed, 275 insertions(+), 3 deletions(-) create mode 100644 cmd/finch/gen_docs_test.go create mode 100644 pkg/mocks/gen_docs_system_deps.go diff --git a/cmd/finch/doc.TEMPLATE.md b/cmd/finch/doc.TEMPLATE.md index c57ad5c16..48f1be131 100644 --- a/cmd/finch/doc.TEMPLATE.md +++ b/cmd/finch/doc.TEMPLATE.md @@ -1,11 +1,14 @@ --- title: "{{ .CmdPath }}" --- -## {{ .CmdPath }} +## {{ .CmdPath }}{{if gt (len .Description) 0}} {{ .Description }} +{{end}} + {{if gt (len .Properties) 0}}### Properties + {{.Properties}} {{end}}``` diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go index 16674c18a..573e2d46b 100644 --- a/cmd/finch/gen_docs.go +++ b/cmd/finch/gen_docs.go @@ -122,7 +122,10 @@ func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) er // redirect Stdout to pipe rescueStdout := gd.deps.Stdout() - r, w, _ := gd.deps.Pipe() + r, w, err := gd.deps.Pipe() + if err != nil { + return fmt.Errorf("error while creating pipe to capture stdout: %w", err) + } gd.deps.SetStdout(w) rootCmd := cmd.Root() @@ -134,6 +137,9 @@ func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) er // rootCmd.SetOutput() would work for all "default finch" commands, but doesn't work // for the nerdctl commands. Getting it to work would remove the need to capture all Stdout. if err := rootCmd.Execute(); err != nil { + // This is pretty much impossible because cobra checks if --help is set and if it is it doesn't + // actually run the command. + // https://github.com/spf13/cobra/blob/main/command.go#L1096-L1099 return fmt.Errorf("error while executing command (args=%v): %w", args, err) } gd.deps.SetStdout(rescueStdout) diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go new file mode 100644 index 000000000..9429804b0 --- /dev/null +++ b/cmd/finch/gen_docs_test.go @@ -0,0 +1,183 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +package main + +import ( + "fmt" + "os" + "testing" + + "github.com/spf13/afero" + "github.com/spf13/cobra" + + "github.com/runfinch/finch/pkg/mocks" + + "github.com/golang/mock/gomock" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestNewGenDocsCommand(t *testing.T) { + t.Parallel() + + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + cmd := newGenDocsCommand(&cobra.Command{}, logger, mFs, deps) + assert.Equal(t, cmd.Name(), "gen-docs") +} + +func TestNewGenDocsGenerateCommand(t *testing.T) { + t.Parallel() + + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + cmd := newGenDocsGenerateCommand(&cobra.Command{}, logger, mFs, deps) + assert.Equal(t, cmd.Name(), "generate") +} + +var codeBlock = "```" + +//nolint:paralleltest // This function manipulates stdout +func TestGenDocsAction_runAdapter(t *testing.T) { + testCases := []struct { + name string + cmd func(t *testing.T) *cobra.Command + mockSvc func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) + want error + postRunCheck func(t *testing.T, fs afero.Fs) + }{ + { + name: "path is set and exists", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + Run: func(_ *cobra.Command, _ []string) {}, + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + require.NoError(t, mFs.Mkdir("outDir", 0o666)) + logger.EXPECT().Infof("Creating doc for command: %s", "test-command") + // Hijack stdout before the command does and replace it with a pipe + stdoutR, stdoutW, err := os.Pipe() + require.NoError(t, err) + os.Stdout = stdoutW + deps.EXPECT().Stdout().Return(os.Stdout) + deps.EXPECT().Pipe().Return(stdoutR, stdoutW, nil) + deps.EXPECT().SetStdout(stdoutW) + deps.EXPECT().SetStdout(os.Stdout) + }, + want: nil, + postRunCheck: func(t *testing.T, fs afero.Fs) { + buf, err := afero.ReadFile(fs, "outDir/test-command.md") + require.NoError(t, err) + require.Equal(t, string(buf), fmt.Sprintf(`--- +title: "test-command" +--- +## test-command + +%s + test-command [flags] +%s +`, codeBlock, codeBlock)) + }, + }, + { + name: "path is set and exists but can't create pipe", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + Run: func(_ *cobra.Command, _ []string) {}, + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + require.NoError(t, mFs.Mkdir("outDir", 0o666)) + logger.EXPECT().Infof("Creating doc for command: %s", "test-command") + stdoutR, stdoutW, err := os.Pipe() + require.NoError(t, err) + deps.EXPECT().Stdout().Return(stdoutW) + deps.EXPECT().Pipe().Return(stdoutR, stdoutW, fmt.Errorf("can't create pipe")) + }, + want: fmt.Errorf("error while creating pipe to capture stdout: %w", fmt.Errorf("can't create pipe")), + postRunCheck: func(t *testing.T, fs afero.Fs) { + buf, err := afero.ReadFile(fs, "outDir/test-command.md") + require.NoError(t, err) + require.Equal(t, buf, []byte(``)) + }, + }, + { + name: "path is set and command is not runnable", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + }, + want: nil, + postRunCheck: func(t *testing.T, fs afero.Fs) { + }, + }, + } + + //nolint:paralleltest // This function manipulates stdout + for _, tc := range testCases { + tc := tc + t.Run(tc.name, func(t *testing.T) { + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + rescueStdout := os.Stdout + tc.mockSvc(ctrl, t, logger, mFs, deps, os.Stdout) + got := newGenDocsGenerateAction(tc.cmd(t), logger, mFs, deps).runAdapter(tc.cmd(t), nil) + os.Stdout = rescueStdout + assert.Equal(t, tc.want, got) + tc.postRunCheck(t, mFs) + }) + } +} diff --git a/cmd/finch/main_test.go b/cmd/finch/main_test.go index 43df113a7..0dc61db00 100644 --- a/cmd/finch/main_test.go +++ b/cmd/finch/main_test.go @@ -139,7 +139,7 @@ func TestNewApp(t *testing.T) { assert.Equal(t, cmd.SilenceUsage, true) assert.Equal(t, cmd.SilenceErrors, true) // confirm the number of command, comprised of nerdctl commands + finch commands (version, vm, support-bundle) - assert.Equal(t, len(cmd.Commands()), len(nerdctlCmds)+3) + assert.Equal(t, len(cmd.Commands()), len(nerdctlCmds)+4) // PersistentPreRunE should set logger level to debug if the debug flag exists. mockCmd := &cobra.Command{} diff --git a/pkg/mocks/gen_docs_system_deps.go b/pkg/mocks/gen_docs_system_deps.go new file mode 100644 index 000000000..465e37894 --- /dev/null +++ b/pkg/mocks/gen_docs_system_deps.go @@ -0,0 +1,80 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +// Code generated by MockGen. DO NOT EDIT. +// Source: gen_docs.go + +// Package mocks is a generated GoMock package. +package mocks + +import ( + os "os" + reflect "reflect" + + gomock "github.com/golang/mock/gomock" +) + +// GenDocsSystemDeps is a mock of GenDocsSystemDeps interface. +type GenDocsSystemDeps struct { + ctrl *gomock.Controller + recorder *GenDocsSystemDepsMockRecorder +} + +// GenDocsSystemDepsMockRecorder is the mock recorder for GenDocsSystemDeps. +type GenDocsSystemDepsMockRecorder struct { + mock *GenDocsSystemDeps +} + +// NewGenDocsSystemDeps creates a new mock instance. +func NewGenDocsSystemDeps(ctrl *gomock.Controller) *GenDocsSystemDeps { + mock := &GenDocsSystemDeps{ctrl: ctrl} + mock.recorder = &GenDocsSystemDepsMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *GenDocsSystemDeps) EXPECT() *GenDocsSystemDepsMockRecorder { + return m.recorder +} + +// Pipe mocks base method. +func (m *GenDocsSystemDeps) Pipe() (*os.File, *os.File, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Pipe") + ret0, _ := ret[0].(*os.File) + ret1, _ := ret[1].(*os.File) + ret2, _ := ret[2].(error) + return ret0, ret1, ret2 +} + +// Pipe indicates an expected call of Pipe. +func (mr *GenDocsSystemDepsMockRecorder) Pipe() *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Pipe", reflect.TypeOf((*GenDocsSystemDeps)(nil).Pipe)) +} + +// SetStdout mocks base method. +func (m *GenDocsSystemDeps) SetStdout(arg0 *os.File) { + m.ctrl.T.Helper() + m.ctrl.Call(m, "SetStdout", arg0) +} + +// SetStdout indicates an expected call of SetStdout. +func (mr *GenDocsSystemDepsMockRecorder) SetStdout(arg0 interface{}) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetStdout", reflect.TypeOf((*GenDocsSystemDeps)(nil).SetStdout), arg0) +} + +// Stdout mocks base method. +func (m *GenDocsSystemDeps) Stdout() *os.File { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Stdout") + ret0, _ := ret[0].(*os.File) + return ret0 +} + +// Stdout indicates an expected call of Stdout. +func (mr *GenDocsSystemDepsMockRecorder) Stdout() *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Stdout", reflect.TypeOf((*GenDocsSystemDeps)(nil).Stdout)) +} From c06d3d06395ee4efcf24f24e6213b9870e013dcd Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 12:41:28 -0400 Subject: [PATCH 04/11] fix mdlint Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE.md | 9 ++++++--- docs/cmd/finch_build.md | 2 ++ docs/cmd/finch_builder.md | 3 +++ docs/cmd/finch_commit.md | 2 ++ docs/cmd/finch_completion_bash.md | 2 ++ docs/cmd/finch_completion_fish.md | 2 ++ docs/cmd/finch_completion_powershell.md | 2 ++ docs/cmd/finch_completion_zsh.md | 2 ++ docs/cmd/finch_compose.md | 3 +++ docs/cmd/finch_container.md | 3 +++ docs/cmd/finch_cp.md | 2 ++ docs/cmd/finch_create.md | 2 ++ docs/cmd/finch_events.md | 2 ++ docs/cmd/finch_exec.md | 2 ++ docs/cmd/finch_help.md | 2 ++ docs/cmd/finch_history.md | 2 ++ docs/cmd/finch_image.md | 3 +++ docs/cmd/finch_images.md | 3 +++ docs/cmd/finch_info.md | 2 ++ docs/cmd/finch_inspect.md | 2 ++ docs/cmd/finch_kill.md | 2 ++ docs/cmd/finch_load.md | 2 ++ docs/cmd/finch_login.md | 2 ++ docs/cmd/finch_logout.md | 2 ++ docs/cmd/finch_logs.md | 2 ++ docs/cmd/finch_network.md | 3 +++ docs/cmd/finch_pause.md | 2 ++ docs/cmd/finch_port.md | 2 ++ docs/cmd/finch_ps.md | 2 ++ docs/cmd/finch_pull.md | 2 ++ docs/cmd/finch_push.md | 2 ++ docs/cmd/finch_restart.md | 2 ++ docs/cmd/finch_rm.md | 2 ++ docs/cmd/finch_rmi.md | 2 ++ docs/cmd/finch_run.md | 2 ++ docs/cmd/finch_save.md | 2 ++ docs/cmd/finch_start.md | 2 ++ docs/cmd/finch_stats.md | 2 ++ docs/cmd/finch_stop.md | 2 ++ docs/cmd/finch_support-bundle_generate.md | 2 ++ docs/cmd/finch_system.md | 3 +++ docs/cmd/finch_tag.md | 2 ++ docs/cmd/finch_top.md | 2 ++ docs/cmd/finch_unpause.md | 2 ++ docs/cmd/finch_update.md | 2 ++ docs/cmd/finch_version.md | 2 ++ docs/cmd/finch_vm_init.md | 2 ++ docs/cmd/finch_vm_remove.md | 2 ++ docs/cmd/finch_vm_start.md | 2 ++ docs/cmd/finch_vm_status.md | 2 ++ docs/cmd/finch_vm_stop.md | 2 ++ docs/cmd/finch_volume.md | 3 +++ docs/cmd/finch_wait.md | 2 ++ 53 files changed, 118 insertions(+), 3 deletions(-) diff --git a/cmd/finch/doc.TEMPLATE.md b/cmd/finch/doc.TEMPLATE.md index 48f1be131..74540aa6d 100644 --- a/cmd/finch/doc.TEMPLATE.md +++ b/cmd/finch/doc.TEMPLATE.md @@ -1,13 +1,12 @@ --- title: "{{ .CmdPath }}" --- + ## {{ .CmdPath }}{{if gt (len .Description) 0}} {{ .Description }} -{{end}} - -{{if gt (len .Properties) 0}}### Properties +{{end}}{{if gt (len .Properties) 0}}### Properties {{.Properties}} @@ -16,19 +15,23 @@ title: "{{ .CmdPath }}" ```{{if gt (len .Aliases) 0}} ### Aliases + {{.Aliases}} {{end}}{{if gt (len .Examples) 0}} ### Examples + {{.Examples}} {{end}}{{if gt (len .Commands) 0}} ### Commands + ``` {{ .Commands }} ```{{end}}{{if gt (len .Options) 0}} ### Options + ``` {{ .Options }} ```{{end}}{{if gt (len .SeeAlso) 0}} diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md index 101c06dd9..d55b1ccca 100644 --- a/docs/cmd/finch_build.md +++ b/docs/cmd/finch_build.md @@ -1,6 +1,7 @@ --- title: "finch build" --- + ## finch build Build an image from a Dockerfile. Needs buildkitd to be running. @@ -11,6 +12,7 @@ finch build [flags] PATH ``` ### Options + ``` --build-arg stringArray Set build-time variables --buildkit-host string BuildKit address [$BUILDKIT_HOST] (default "unix:///run/buildkit/buildkitd.sock") diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md index 3dddea16e..0c36817c0 100644 --- a/docs/cmd/finch_builder.md +++ b/docs/cmd/finch_builder.md @@ -1,6 +1,7 @@ --- title: "finch builder" --- + ## finch builder Manage builds @@ -10,6 +11,7 @@ finch builder [flags] ``` ### Commands + ``` build Build an image from a Dockerfile. Needs buildkitd to be running. debug Debug Dockerfile @@ -17,6 +19,7 @@ finch builder [flags] ``` ### Options + ``` -h, --help help for builder ``` diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md index 4e889d4a2..8fa30ccac 100644 --- a/docs/cmd/finch_commit.md +++ b/docs/cmd/finch_commit.md @@ -1,6 +1,7 @@ --- title: "finch commit" --- + ## finch commit Create a new image from a container's changes @@ -10,6 +11,7 @@ finch commit [flags] CONTAINER REPOSITORY[:TAG] ``` ### Options + ``` -a, --author string Author (e.g., "finch contributor ") -c, --change stringArray Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md index f6d75eacb..50e287309 100644 --- a/docs/cmd/finch_completion_bash.md +++ b/docs/cmd/finch_completion_bash.md @@ -1,6 +1,7 @@ --- title: "finch completion bash" --- + ## finch completion bash Generate the autocompletion script for the bash shell. @@ -21,6 +22,7 @@ To load completions for every new session, execute once: ``` ### Options + ``` -h, --help help for bash --no-descriptions disable completion descriptions diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md index 854c0481b..2d4872e3e 100644 --- a/docs/cmd/finch_completion_fish.md +++ b/docs/cmd/finch_completion_fish.md @@ -1,6 +1,7 @@ --- title: "finch completion fish" --- + ## finch completion fish Generate the autocompletion script for the fish shell. @@ -20,6 +21,7 @@ You will need to start a new shell for this setup to take effect. ``` ### Options + ``` -h, --help help for fish --no-descriptions disable completion descriptions diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md index e28138b28..d4d899575 100644 --- a/docs/cmd/finch_completion_powershell.md +++ b/docs/cmd/finch_completion_powershell.md @@ -1,6 +1,7 @@ --- title: "finch completion powershell" --- + ## finch completion powershell Generate the autocompletion script for powershell. @@ -17,6 +18,7 @@ to your powershell profile. ``` ### Options + ``` -h, --help help for powershell --no-descriptions disable completion descriptions diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md index d1dd6e4d1..cd69f7675 100644 --- a/docs/cmd/finch_completion_zsh.md +++ b/docs/cmd/finch_completion_zsh.md @@ -1,6 +1,7 @@ --- title: "finch completion zsh" --- + ## finch completion zsh Generate the autocompletion script for the zsh shell. @@ -23,6 +24,7 @@ To load completions for every new session, execute once: ``` ### Options + ``` -h, --help help for zsh --no-descriptions disable completion descriptions diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md index 9a4eefd1e..d652240a0 100644 --- a/docs/cmd/finch_compose.md +++ b/docs/cmd/finch_compose.md @@ -1,6 +1,7 @@ --- title: "finch compose" --- + ## finch compose Compose @@ -10,6 +11,7 @@ finch compose [flags] COMMAND ``` ### Commands + ``` build Build or rebuild services config Validate and view the Compose file @@ -37,6 +39,7 @@ finch compose [flags] COMMAND ``` ### Options + ``` --env-file string Specify an alternate environment file -f, --f stringArray Alias of --file diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md index bee0536da..f7a69da78 100644 --- a/docs/cmd/finch_container.md +++ b/docs/cmd/finch_container.md @@ -1,6 +1,7 @@ --- title: "finch container" --- + ## finch container Manage containers @@ -10,6 +11,7 @@ finch container [flags] ``` ### Commands + ``` attach Attach stdin, stdout, and stderr to a running container. commit Create a new image from a container's changes @@ -36,6 +38,7 @@ finch container [flags] ``` ### Options + ``` -h, --help help for container ``` diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md index 10dd823dc..37e3e699a 100644 --- a/docs/cmd/finch_cp.md +++ b/docs/cmd/finch_cp.md @@ -1,6 +1,7 @@ --- title: "finch cp" --- + ## finch cp Copy files/folders between a running container and the local filesystem. @@ -14,6 +15,7 @@ finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|- ``` ### Options + ``` -L, --follow-link Always follow symbolic link in SRC_PATH. -h, --help help for cp diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md index 9c0fd2585..7b896fb6b 100644 --- a/docs/cmd/finch_create.md +++ b/docs/cmd/finch_create.md @@ -1,6 +1,7 @@ --- title: "finch create" --- + ## finch create Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,6 +11,7 @@ finch create [flags] IMAGE [COMMAND] [ARG...] ``` ### Options + ``` --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) diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md index d4df03517..ff692cb45 100644 --- a/docs/cmd/finch_events.md +++ b/docs/cmd/finch_events.md @@ -1,6 +1,7 @@ --- title: "finch events" --- + ## finch events Get real time events from the server @@ -10,6 +11,7 @@ finch events [flags] ``` ### Options + ``` --format string Format the output using the given Go template, e.g, '{{json .}}' -h, --help help for events diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md index 970d53582..c71dea488 100644 --- a/docs/cmd/finch_exec.md +++ b/docs/cmd/finch_exec.md @@ -1,6 +1,7 @@ --- title: "finch exec" --- + ## finch exec Run a command in a running container @@ -10,6 +11,7 @@ finch exec [flags] CONTAINER COMMAND [ARG...] ``` ### Options + ``` -d, --detach Detached mode: run command in the background -e, --env stringArray Set environment variables diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md index f5c2eab8b..8be87b125 100644 --- a/docs/cmd/finch_help.md +++ b/docs/cmd/finch_help.md @@ -1,6 +1,7 @@ --- title: "finch help" --- + ## finch help Help provides help for any command in the application. @@ -11,6 +12,7 @@ Simply type finch help [path to command] for full details. ``` ### Options + ``` -h, --help help for help ``` diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md index cbef21d69..be4dc3509 100644 --- a/docs/cmd/finch_history.md +++ b/docs/cmd/finch_history.md @@ -1,6 +1,7 @@ --- title: "finch history" --- + ## finch history Show the history of an image @@ -10,6 +11,7 @@ finch history [flags] IMAGE ``` ### Options + ``` -f, --format string Format the output using the given Go template, e.g, '{{json .}}' -h, --help help for history diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md index 932c6bde4..7a3b1c3ea 100644 --- a/docs/cmd/finch_image.md +++ b/docs/cmd/finch_image.md @@ -1,6 +1,7 @@ --- title: "finch image" --- + ## finch image Manage images @@ -10,6 +11,7 @@ finch image [flags] ``` ### Commands + ``` build Build an image from a Dockerfile. Needs buildkitd to be running. convert convert an image @@ -28,6 +30,7 @@ finch image [flags] ``` ### Options + ``` -h, --help help for image ``` diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md index 3a11e68d1..798253aaa 100644 --- a/docs/cmd/finch_images.md +++ b/docs/cmd/finch_images.md @@ -1,11 +1,13 @@ --- title: "finch images" --- + ## finch images List images ### Properties + - REPOSITORY: Repository - TAG: Tag - NAME: Name of the image, --names for skip parsing as repository and tag. @@ -20,6 +22,7 @@ finch images [flags] [REPOSITORY[:TAG]] ``` ### Options + ``` -a, --all (unimplemented yet, always true) (default true) --digests Show digests (compatible with Docker, unlike ID) diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md index 1d4dab6aa..a6b96b399 100644 --- a/docs/cmd/finch_info.md +++ b/docs/cmd/finch_info.md @@ -1,6 +1,7 @@ --- title: "finch info" --- + ## finch info Display system-wide information @@ -10,6 +11,7 @@ finch info [flags] ``` ### Options + ``` -f, --format string Format the output using the given Go template, e.g, '{{json .}}' -h, --help help for info diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md index 40cf06a28..aa9d87bd7 100644 --- a/docs/cmd/finch_inspect.md +++ b/docs/cmd/finch_inspect.md @@ -1,6 +1,7 @@ --- title: "finch inspect" --- + ## finch inspect Return low-level information on objects. @@ -10,6 +11,7 @@ finch inspect [flags] ``` ### Options + ``` -f, --format string Format the output using the given Go template, e.g, '{{json .}}' -h, --help help for inspect diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md index 82345fff7..10f5c3e5e 100644 --- a/docs/cmd/finch_kill.md +++ b/docs/cmd/finch_kill.md @@ -1,6 +1,7 @@ --- title: "finch kill" --- + ## finch kill Kill one or more running containers @@ -10,6 +11,7 @@ finch kill [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for kill -s, --signal string Signal to send to the container (default "KILL") diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md index fe044d04b..ee50be592 100644 --- a/docs/cmd/finch_load.md +++ b/docs/cmd/finch_load.md @@ -1,6 +1,7 @@ --- title: "finch load" --- + ## finch load Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. @@ -10,6 +11,7 @@ finch load [flags] ``` ### Options + ``` --all-platforms Import content for all platforms -h, --help help for load diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md index 0ec907e76..9e73414cb 100644 --- a/docs/cmd/finch_login.md +++ b/docs/cmd/finch_login.md @@ -1,6 +1,7 @@ --- title: "finch login" --- + ## finch login Log in to a container registry @@ -10,6 +11,7 @@ finch login [flags] [SERVER] ``` ### Options + ``` -h, --help help for login -p, --password string Password diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md index 6e6ccafd5..2cd697845 100644 --- a/docs/cmd/finch_logout.md +++ b/docs/cmd/finch_logout.md @@ -1,6 +1,7 @@ --- title: "finch logout" --- + ## finch logout Log out from a container registry @@ -10,6 +11,7 @@ finch logout [flags] [SERVER] ``` ### Options + ``` -h, --help help for logout ``` diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md index a31275353..d466786a6 100644 --- a/docs/cmd/finch_logs.md +++ b/docs/cmd/finch_logs.md @@ -1,6 +1,7 @@ --- title: "finch logs" --- + ## finch logs Fetch the logs of a container. @@ -15,6 +16,7 @@ finch logs [flags] CONTAINER ``` ### Options + ``` -f, --follow Follow log output -h, --help help for logs diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md index 1a3d04670..cb8f11241 100644 --- a/docs/cmd/finch_network.md +++ b/docs/cmd/finch_network.md @@ -1,6 +1,7 @@ --- title: "finch network" --- + ## finch network Manage networks @@ -10,6 +11,7 @@ finch network [flags] ``` ### Commands + ``` create Create a network inspect Display detailed information on one or more networks @@ -19,6 +21,7 @@ finch network [flags] ``` ### Options + ``` -h, --help help for network ``` diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md index 518bd72bc..80834df58 100644 --- a/docs/cmd/finch_pause.md +++ b/docs/cmd/finch_pause.md @@ -1,6 +1,7 @@ --- title: "finch pause" --- + ## finch pause Pause all processes within one or more containers @@ -10,6 +11,7 @@ finch pause [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for pause ``` diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md index 7011764ac..afb7384d3 100644 --- a/docs/cmd/finch_port.md +++ b/docs/cmd/finch_port.md @@ -1,6 +1,7 @@ --- title: "finch port" --- + ## finch port List port mappings or a specific mapping for the container @@ -10,6 +11,7 @@ finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] ``` ### Options + ``` -h, --help help for port ``` diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md index 2fbfe2414..ac6ea4055 100644 --- a/docs/cmd/finch_ps.md +++ b/docs/cmd/finch_ps.md @@ -1,6 +1,7 @@ --- title: "finch ps" --- + ## finch ps List containers @@ -10,6 +11,7 @@ finch ps [flags] ``` ### Options + ``` -a, --all Show all containers (default shows just running) -f, --filter strings Filter matches containers based on given conditions diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md index 9a66b87f1..ad135d142 100644 --- a/docs/cmd/finch_pull.md +++ b/docs/cmd/finch_pull.md @@ -1,6 +1,7 @@ --- title: "finch pull" --- + ## finch pull Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,6 +11,7 @@ finch pull [flags] NAME[:TAG] ``` ### Options + ``` --all-platforms Pull content for all platforms --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md index 75736c20d..155599c5c 100644 --- a/docs/cmd/finch_push.md +++ b/docs/cmd/finch_push.md @@ -1,6 +1,7 @@ --- title: "finch push" --- + ## finch push Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. @@ -10,6 +11,7 @@ finch push [flags] NAME[:TAG] ``` ### Options + ``` --all-platforms Push content for all platforms --allow-nondistributable-artifacts Allow pushing images with non-distributable blobs diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md index ccd69ebda..7ee5d6d3a 100644 --- a/docs/cmd/finch_restart.md +++ b/docs/cmd/finch_restart.md @@ -1,6 +1,7 @@ --- title: "finch restart" --- + ## finch restart Restart one or more running containers @@ -10,6 +11,7 @@ finch restart [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for restart -t, --time uint Seconds to wait for stop before killing it (default 10) diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md index 0bfb91589..9d79121d5 100644 --- a/docs/cmd/finch_rm.md +++ b/docs/cmd/finch_rm.md @@ -1,6 +1,7 @@ --- title: "finch rm" --- + ## finch rm Remove one or more containers @@ -10,6 +11,7 @@ finch rm [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) -h, --help help for rm diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md index a48a0a07e..d38edebdb 100644 --- a/docs/cmd/finch_rmi.md +++ b/docs/cmd/finch_rmi.md @@ -1,6 +1,7 @@ --- title: "finch rmi" --- + ## finch rmi Remove one or more images @@ -10,6 +11,7 @@ finch rmi [flags] IMAGE [IMAGE, ...] ``` ### Options + ``` --async Asynchronous mode -f, --force Force removal of the image diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md index 15f1570a3..af3b6460e 100644 --- a/docs/cmd/finch_run.md +++ b/docs/cmd/finch_run.md @@ -1,6 +1,7 @@ --- title: "finch run" --- + ## finch run Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,6 +11,7 @@ finch run [flags] IMAGE [COMMAND] [ARG...] ``` ### Options + ``` --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) diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md index d9af9af84..17ef3bec0 100644 --- a/docs/cmd/finch_save.md +++ b/docs/cmd/finch_save.md @@ -1,6 +1,7 @@ --- title: "finch save" --- + ## finch save The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. @@ -10,6 +11,7 @@ finch save [flags] ``` ### Options + ``` --all-platforms Export content for all platforms -h, --help help for save diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md index fe9fe15fd..a9dc69bf5 100644 --- a/docs/cmd/finch_start.md +++ b/docs/cmd/finch_start.md @@ -1,6 +1,7 @@ --- title: "finch start" --- + ## finch start Start one or more running containers @@ -10,6 +11,7 @@ finch start [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -a, --attach Attach STDOUT/STDERR and forward signals --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md index 9d6b47c5a..0f92337bf 100644 --- a/docs/cmd/finch_stats.md +++ b/docs/cmd/finch_stats.md @@ -1,6 +1,7 @@ --- title: "finch stats" --- + ## finch stats Display a live stream of container(s) resource usage statistics. @@ -10,6 +11,7 @@ finch stats [flags] ``` ### Options + ``` -a, --all Show all containers (default shows just running) --format string Pretty-print images using a Go template, e.g, '{{json .}}' diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md index 9c9bb119a..d54f96ad2 100644 --- a/docs/cmd/finch_stop.md +++ b/docs/cmd/finch_stop.md @@ -1,6 +1,7 @@ --- title: "finch stop" --- + ## finch stop Stop one or more running containers @@ -10,6 +11,7 @@ finch stop [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for stop -t, --time int Seconds to wait before sending a SIGKILL (default 10) diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md index f4470e8fb..353404fb3 100644 --- a/docs/cmd/finch_support-bundle_generate.md +++ b/docs/cmd/finch_support-bundle_generate.md @@ -1,6 +1,7 @@ --- title: "finch support-bundle generate" --- + ## finch support-bundle generate Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. @@ -10,6 +11,7 @@ Generates a collection of logs and configs that can be uploaded to a Github issu ``` ### Options + ``` --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded -h, --help help for generate diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md index e9ef646ea..c2f120f07 100644 --- a/docs/cmd/finch_system.md +++ b/docs/cmd/finch_system.md @@ -1,6 +1,7 @@ --- title: "finch system" --- + ## finch system Manage containerd @@ -10,6 +11,7 @@ finch system [flags] ``` ### Commands + ``` events Get real time events from the server info Display system-wide information @@ -17,6 +19,7 @@ finch system [flags] ``` ### Options + ``` -h, --help help for system ``` diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md index 81e4f347f..2cb4b1934 100644 --- a/docs/cmd/finch_tag.md +++ b/docs/cmd/finch_tag.md @@ -1,6 +1,7 @@ --- title: "finch tag" --- + ## finch tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE @@ -10,6 +11,7 @@ finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] ``` ### Options + ``` -h, --help help for tag ``` diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md index cddf61bf6..e2b31d23d 100644 --- a/docs/cmd/finch_top.md +++ b/docs/cmd/finch_top.md @@ -1,6 +1,7 @@ --- title: "finch top" --- + ## finch top Display the running processes of a container @@ -10,6 +11,7 @@ finch top CONTAINER [ps OPTIONS] [flags] ``` ### Options + ``` -h, --help help for top ``` diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md index e3d9b1382..391ac4d0f 100644 --- a/docs/cmd/finch_unpause.md +++ b/docs/cmd/finch_unpause.md @@ -1,6 +1,7 @@ --- title: "finch unpause" --- + ## finch unpause Unpause all processes within one or more containers @@ -10,6 +11,7 @@ finch unpause [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for unpause ``` diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md index b13427b97..1879e3f0f 100644 --- a/docs/cmd/finch_update.md +++ b/docs/cmd/finch_update.md @@ -1,6 +1,7 @@ --- title: "finch update" --- + ## finch update Update one or more running containers @@ -10,6 +11,7 @@ finch update [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md index 7261a8605..39cd9a438 100644 --- a/docs/cmd/finch_version.md +++ b/docs/cmd/finch_version.md @@ -1,6 +1,7 @@ --- title: "finch version" --- + ## finch version Shows Finch version information @@ -10,6 +11,7 @@ Shows Finch version information ``` ### Options + ``` -h, --help help for version ``` diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md index 232141d72..e273d160d 100644 --- a/docs/cmd/finch_vm_init.md +++ b/docs/cmd/finch_vm_init.md @@ -1,6 +1,7 @@ --- title: "finch vm init" --- + ## finch vm init Initialize the virtual machine @@ -10,6 +11,7 @@ Initialize the virtual machine ``` ### Options + ``` -h, --help help for init ``` diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md index 8ee73973f..8423d0239 100644 --- a/docs/cmd/finch_vm_remove.md +++ b/docs/cmd/finch_vm_remove.md @@ -1,6 +1,7 @@ --- title: "finch vm remove" --- + ## finch vm remove Remove the virtual machine instance @@ -10,6 +11,7 @@ Remove the virtual machine instance ``` ### Options + ``` -f, --force forcibly remove finch VM -h, --help help for remove diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md index dcf3a6ea6..3fb9bbdbc 100644 --- a/docs/cmd/finch_vm_start.md +++ b/docs/cmd/finch_vm_start.md @@ -1,6 +1,7 @@ --- title: "finch vm start" --- + ## finch vm start Start the virtual machine @@ -10,6 +11,7 @@ Start the virtual machine ``` ### Options + ``` -h, --help help for start ``` diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md index 342c4b46a..73a46d852 100644 --- a/docs/cmd/finch_vm_status.md +++ b/docs/cmd/finch_vm_status.md @@ -1,6 +1,7 @@ --- title: "finch vm status" --- + ## finch vm status Status of the virtual machine @@ -10,6 +11,7 @@ Status of the virtual machine ``` ### Options + ``` -h, --help help for status ``` diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md index 1722e968f..7eaed00bf 100644 --- a/docs/cmd/finch_vm_stop.md +++ b/docs/cmd/finch_vm_stop.md @@ -1,6 +1,7 @@ --- title: "finch vm stop" --- + ## finch vm stop Stop the virtual machine @@ -10,6 +11,7 @@ Stop the virtual machine ``` ### Options + ``` -f, --force forcibly stop finch VM -h, --help help for stop diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md index 0734da547..44a22dfe9 100644 --- a/docs/cmd/finch_volume.md +++ b/docs/cmd/finch_volume.md @@ -1,6 +1,7 @@ --- title: "finch volume" --- + ## finch volume Manage volumes @@ -10,6 +11,7 @@ finch volume [flags] ``` ### Commands + ``` create Create a volume inspect Display detailed information on one or more volumes @@ -19,6 +21,7 @@ finch volume [flags] ``` ### Options + ``` -h, --help help for volume ``` diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md index 705746ef1..299a65248 100644 --- a/docs/cmd/finch_wait.md +++ b/docs/cmd/finch_wait.md @@ -1,6 +1,7 @@ --- title: "finch wait" --- + ## finch wait Block until one or more containers stop, then print their exit codes. @@ -10,6 +11,7 @@ finch wait [flags] CONTAINER [CONTAINER, ...] ``` ### Options + ``` -h, --help help for wait ``` From 36e4df44b55b0afa9cf8dbb75c95beaffae3b2fc Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 13:01:39 -0400 Subject: [PATCH 05/11] fix mdlint (for real) Signed-off-by: Justin Alvarez --- .markdownlintignore | 6 ++++++ cmd/finch/{doc.TEMPLATE.md => doc.TEMPLATE} | 6 +++--- cmd/finch/gen_docs.go | 2 +- docs/cmd/finch_build.md | 4 ++-- docs/cmd/finch_builder.md | 6 +++--- docs/cmd/finch_commit.md | 4 ++-- docs/cmd/finch_completion_bash.md | 4 ++-- docs/cmd/finch_completion_fish.md | 4 ++-- docs/cmd/finch_completion_powershell.md | 4 ++-- docs/cmd/finch_completion_zsh.md | 4 ++-- docs/cmd/finch_compose.md | 6 +++--- docs/cmd/finch_container.md | 6 +++--- docs/cmd/finch_cp.md | 4 ++-- docs/cmd/finch_create.md | 4 ++-- docs/cmd/finch_events.md | 4 ++-- docs/cmd/finch_exec.md | 4 ++-- docs/cmd/finch_help.md | 4 ++-- docs/cmd/finch_history.md | 4 ++-- docs/cmd/finch_image.md | 6 +++--- docs/cmd/finch_images.md | 4 ++-- docs/cmd/finch_info.md | 4 ++-- docs/cmd/finch_inspect.md | 4 ++-- docs/cmd/finch_kill.md | 4 ++-- docs/cmd/finch_load.md | 4 ++-- docs/cmd/finch_login.md | 4 ++-- docs/cmd/finch_logout.md | 4 ++-- docs/cmd/finch_logs.md | 4 ++-- docs/cmd/finch_network.md | 6 +++--- docs/cmd/finch_pause.md | 4 ++-- docs/cmd/finch_port.md | 4 ++-- docs/cmd/finch_ps.md | 4 ++-- docs/cmd/finch_pull.md | 4 ++-- docs/cmd/finch_push.md | 4 ++-- docs/cmd/finch_restart.md | 4 ++-- docs/cmd/finch_rm.md | 4 ++-- docs/cmd/finch_rmi.md | 4 ++-- docs/cmd/finch_run.md | 4 ++-- docs/cmd/finch_save.md | 4 ++-- docs/cmd/finch_start.md | 4 ++-- docs/cmd/finch_stats.md | 4 ++-- docs/cmd/finch_stop.md | 4 ++-- docs/cmd/finch_support-bundle_generate.md | 4 ++-- docs/cmd/finch_system.md | 6 +++--- docs/cmd/finch_tag.md | 4 ++-- docs/cmd/finch_top.md | 4 ++-- docs/cmd/finch_unpause.md | 4 ++-- docs/cmd/finch_update.md | 4 ++-- docs/cmd/finch_version.md | 4 ++-- docs/cmd/finch_vm_init.md | 4 ++-- docs/cmd/finch_vm_remove.md | 4 ++-- docs/cmd/finch_vm_start.md | 4 ++-- docs/cmd/finch_vm_status.md | 4 ++-- docs/cmd/finch_vm_stop.md | 4 ++-- docs/cmd/finch_volume.md | 6 +++--- docs/cmd/finch_wait.md | 4 ++-- 55 files changed, 121 insertions(+), 115 deletions(-) create mode 100644 .markdownlintignore rename cmd/finch/{doc.TEMPLATE.md => doc.TEMPLATE} (94%) diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..30628358c --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,6 @@ +deps/ +# Since the current documentation generation works by just capturing stdout, we don't do any post processing +# The completion files have issues with code block style +docs/cmd/*completion*.md +# finch_logs.md has issues with the list not being surrounded by newlines +docs/cmd/finch_logs.md diff --git a/cmd/finch/doc.TEMPLATE.md b/cmd/finch/doc.TEMPLATE similarity index 94% rename from cmd/finch/doc.TEMPLATE.md rename to cmd/finch/doc.TEMPLATE index 74540aa6d..af7477d63 100644 --- a/cmd/finch/doc.TEMPLATE.md +++ b/cmd/finch/doc.TEMPLATE @@ -10,7 +10,7 @@ title: "{{ .CmdPath }}" {{.Properties}} -{{end}}``` +{{end}}```bash {{ .Usage }} ```{{if gt (len .Aliases) 0}} @@ -26,13 +26,13 @@ title: "{{ .CmdPath }}" ### Commands -``` +```bash {{ .Commands }} ```{{end}}{{if gt (len .Options) 0}} ### Options -``` +```bash {{ .Options }} ```{{end}}{{if gt (len .SeeAlso) 0}} diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go index 573e2d46b..d6d7f9f73 100644 --- a/cmd/finch/gen_docs.go +++ b/cmd/finch/gen_docs.go @@ -173,7 +173,7 @@ func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) er return nil } -//go:embed doc.TEMPLATE.md +//go:embed doc.TEMPLATE var docTmpl string type docTmplOpts struct { diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md index d55b1ccca..d4b4f4127 100644 --- a/docs/cmd/finch_build.md +++ b/docs/cmd/finch_build.md @@ -7,13 +7,13 @@ title: "finch build" 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 finch build [flags] PATH ``` ### Options -``` +```bash --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) diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md index 0c36817c0..6ab987ee9 100644 --- a/docs/cmd/finch_builder.md +++ b/docs/cmd/finch_builder.md @@ -6,13 +6,13 @@ title: "finch builder" Manage builds -``` +```bash finch builder [flags] ``` ### Commands -``` +```bash build Build an image from a Dockerfile. Needs buildkitd to be running. debug Debug Dockerfile prune Clean up BuildKit build cache @@ -20,6 +20,6 @@ finch builder [flags] ### Options -``` +```bash -h, --help help for builder ``` diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md index 8fa30ccac..b428685ab 100644 --- a/docs/cmd/finch_commit.md +++ b/docs/cmd/finch_commit.md @@ -6,13 +6,13 @@ title: "finch commit" Create a new image from a container's changes -``` +```bash finch commit [flags] CONTAINER REPOSITORY[:TAG] ``` ### Options -``` +```bash -a, --author string Author (e.g., "finch contributor ") -c, --change stringArray Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) -h, --help help for commit diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md index 50e287309..a0628e5e9 100644 --- a/docs/cmd/finch_completion_bash.md +++ b/docs/cmd/finch_completion_bash.md @@ -17,13 +17,13 @@ To load completions for every new session, execute once: #### -``` +```bash finch completion bash ``` ### Options -``` +```bash -h, --help help for bash --no-descriptions disable completion descriptions ``` diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md index 2d4872e3e..d44095316 100644 --- a/docs/cmd/finch_completion_fish.md +++ b/docs/cmd/finch_completion_fish.md @@ -16,13 +16,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 finch completion fish [flags] ``` ### Options -``` +```bash -h, --help help for fish --no-descriptions disable completion descriptions ``` diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md index d4d899575..b10191d93 100644 --- a/docs/cmd/finch_completion_powershell.md +++ b/docs/cmd/finch_completion_powershell.md @@ -13,13 +13,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 finch completion powershell [flags] ``` ### Options -``` +```bash -h, --help help for powershell --no-descriptions disable completion descriptions ``` diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md index cd69f7675..e31c7543e 100644 --- a/docs/cmd/finch_completion_zsh.md +++ b/docs/cmd/finch_completion_zsh.md @@ -19,13 +19,13 @@ To load completions for every new session, execute once: #### -``` +```bash finch completion zsh [flags] ``` ### Options -``` +```bash -h, --help help for zsh --no-descriptions disable completion descriptions ``` diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md index d652240a0..52ad52d80 100644 --- a/docs/cmd/finch_compose.md +++ b/docs/cmd/finch_compose.md @@ -6,13 +6,13 @@ title: "finch compose" Compose -``` +```bash finch compose [flags] COMMAND ``` ### Commands -``` +```bash build Build or rebuild services config Validate and view the Compose file cp Copy files/folders between a service container and the local filesystem @@ -40,7 +40,7 @@ finch compose [flags] COMMAND ### Options -``` +```bash --env-file string Specify an alternate environment file -f, --f stringArray Alias of --file --file stringArray Specify an alternate compose file diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md index f7a69da78..82feb3b66 100644 --- a/docs/cmd/finch_container.md +++ b/docs/cmd/finch_container.md @@ -6,13 +6,13 @@ title: "finch container" Manage containers -``` +```bash finch container [flags] ``` ### Commands -``` +```bash 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. @@ -39,6 +39,6 @@ finch container [flags] ### Options -``` +```bash -h, --help help for container ``` diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md index 37e3e699a..bc7ce2338 100644 --- a/docs/cmd/finch_cp.md +++ b/docs/cmd/finch_cp.md @@ -9,14 +9,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 finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|- finch cp [flags] SRC_PATH|- CONTAINER:DEST_PATH ``` ### Options -``` +```bash -L, --follow-link Always follow symbolic link in SRC_PATH. -h, --help help for cp ``` diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md index 7b896fb6b..f23b98a95 100644 --- a/docs/cmd/finch_create.md +++ b/docs/cmd/finch_create.md @@ -6,13 +6,13 @@ title: "finch create" Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. -``` +```bash finch create [flags] IMAGE [COMMAND] [ARG...] ``` ### Options -``` +```bash --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 diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md index ff692cb45..c0759bfdf 100644 --- a/docs/cmd/finch_events.md +++ b/docs/cmd/finch_events.md @@ -6,13 +6,13 @@ title: "finch events" Get real time events from the server -``` +```bash finch events [flags] ``` ### Options -``` +```bash --format string Format the output using the given Go template, e.g, '{{json .}}' -h, --help help for events ``` diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md index c71dea488..4361fef87 100644 --- a/docs/cmd/finch_exec.md +++ b/docs/cmd/finch_exec.md @@ -6,13 +6,13 @@ title: "finch exec" Run a command in a running container -``` +```bash finch exec [flags] CONTAINER COMMAND [ARG...] ``` ### Options -``` +```bash -d, --detach Detached mode: run command in the background -e, --env stringArray Set environment variables --env-file strings Set environment variables from file diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md index 8be87b125..f8bccccef 100644 --- a/docs/cmd/finch_help.md +++ b/docs/cmd/finch_help.md @@ -7,12 +7,12 @@ title: "finch help" Help provides help for any command in the application. Simply type finch help [path to command] for full details. -``` +```bash finch help [command] [flags] ``` ### Options -``` +```bash -h, --help help for help ``` diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md index be4dc3509..6d95253cb 100644 --- a/docs/cmd/finch_history.md +++ b/docs/cmd/finch_history.md @@ -6,13 +6,13 @@ title: "finch history" Show the history of an image -``` +```bash finch history [flags] IMAGE ``` ### Options -``` +```bash -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 diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md index 7a3b1c3ea..bb4183624 100644 --- a/docs/cmd/finch_image.md +++ b/docs/cmd/finch_image.md @@ -6,13 +6,13 @@ title: "finch image" Manage images -``` +```bash finch image [flags] ``` ### Commands -``` +```bash build Build an image from a Dockerfile. Needs buildkitd to be running. convert convert an image decrypt decrypt an image @@ -31,6 +31,6 @@ finch image [flags] ### Options -``` +```bash -h, --help help for image ``` diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md index 798253aaa..7ec6bace2 100644 --- a/docs/cmd/finch_images.md +++ b/docs/cmd/finch_images.md @@ -17,13 +17,13 @@ List images - SIZE: Size of the unpacked snapshots - BLOB SIZE: Size of the blobs (such as layer tarballs) in the content store -``` +```bash finch images [flags] [REPOSITORY[:TAG]] ``` ### Options -``` +```bash -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 diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md index a6b96b399..3334459b4 100644 --- a/docs/cmd/finch_info.md +++ b/docs/cmd/finch_info.md @@ -6,13 +6,13 @@ title: "finch info" Display system-wide information -``` +```bash finch info [flags] ``` ### Options -``` +```bash -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") diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md index aa9d87bd7..440999d00 100644 --- a/docs/cmd/finch_inspect.md +++ b/docs/cmd/finch_inspect.md @@ -6,13 +6,13 @@ title: "finch inspect" Return low-level information on objects. -``` +```bash finch inspect [flags] ``` ### Options -``` +```bash -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") diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md index 10f5c3e5e..6b073dbb4 100644 --- a/docs/cmd/finch_kill.md +++ b/docs/cmd/finch_kill.md @@ -6,13 +6,13 @@ title: "finch kill" Kill one or more running containers -``` +```bash finch kill [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for kill -s, --signal string Signal to send to the container (default "KILL") ``` diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md index ee50be592..51b18c356 100644 --- a/docs/cmd/finch_load.md +++ b/docs/cmd/finch_load.md @@ -6,13 +6,13 @@ title: "finch load" Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. -``` +```bash finch load [flags] ``` ### Options -``` +```bash --all-platforms Import content for all platforms -h, --help help for load -i, --input string Read from tar archive file, instead of STDIN diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md index 9e73414cb..21383a935 100644 --- a/docs/cmd/finch_login.md +++ b/docs/cmd/finch_login.md @@ -6,13 +6,13 @@ title: "finch login" Log in to a container registry -``` +```bash finch login [flags] [SERVER] ``` ### Options -``` +```bash -h, --help help for login -p, --password string Password --password-stdin Take the password from stdin diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md index 2cd697845..3cb026552 100644 --- a/docs/cmd/finch_logout.md +++ b/docs/cmd/finch_logout.md @@ -6,12 +6,12 @@ title: "finch logout" Log out from a container registry -``` +```bash finch logout [flags] [SERVER] ``` ### Options -``` +```bash -h, --help help for logout ``` diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md index d466786a6..606fdecc0 100644 --- a/docs/cmd/finch_logs.md +++ b/docs/cmd/finch_logs.md @@ -11,13 +11,13 @@ The following containers are supported: - Containers created with 'finch compose'. - Containers created with Kubernetes (EXPERIMENTAL). -``` +```bash finch logs [flags] CONTAINER ``` ### Options -``` +```bash -f, --follow Follow log output -h, --help help for logs --since string Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md index cb8f11241..9fbb576f2 100644 --- a/docs/cmd/finch_network.md +++ b/docs/cmd/finch_network.md @@ -6,13 +6,13 @@ title: "finch network" Manage networks -``` +```bash finch network [flags] ``` ### Commands -``` +```bash create Create a network inspect Display detailed information on one or more networks ls List networks @@ -22,6 +22,6 @@ finch network [flags] ### Options -``` +```bash -h, --help help for network ``` diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md index 80834df58..9096bafd9 100644 --- a/docs/cmd/finch_pause.md +++ b/docs/cmd/finch_pause.md @@ -6,12 +6,12 @@ title: "finch pause" Pause all processes within one or more containers -``` +```bash finch pause [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for pause ``` diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md index afb7384d3..2add36cce 100644 --- a/docs/cmd/finch_port.md +++ b/docs/cmd/finch_port.md @@ -6,12 +6,12 @@ title: "finch port" List port mappings or a specific mapping for the container -``` +```bash finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] ``` ### Options -``` +```bash -h, --help help for port ``` diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md index ac6ea4055..6886cbeee 100644 --- a/docs/cmd/finch_ps.md +++ b/docs/cmd/finch_ps.md @@ -6,13 +6,13 @@ title: "finch ps" List containers -``` +```bash finch ps [flags] ``` ### Options -``` +```bash -a, --all Show all containers (default shows just running) -f, --filter strings Filter matches containers based on given conditions --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md index ad135d142..38ef06d89 100644 --- a/docs/cmd/finch_pull.md +++ b/docs/cmd/finch_pull.md @@ -6,13 +6,13 @@ title: "finch pull" Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. -``` +```bash finch pull [flags] NAME[:TAG] ``` ### Options -``` +```bash --all-platforms Pull content for all platforms --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md index 155599c5c..2fca75c2b 100644 --- a/docs/cmd/finch_push.md +++ b/docs/cmd/finch_push.md @@ -6,13 +6,13 @@ title: "finch push" Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. -``` +```bash finch push [flags] NAME[:TAG] ``` ### Options -``` +```bash --all-platforms Push content for all platforms --allow-nondistributable-artifacts Allow pushing images with non-distributable blobs --cosign-key string Path to the private key file, KMS URI or Kubernetes Secret for --sign=cosign diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md index 7ee5d6d3a..3d48d02d4 100644 --- a/docs/cmd/finch_restart.md +++ b/docs/cmd/finch_restart.md @@ -6,13 +6,13 @@ title: "finch restart" Restart one or more running containers -``` +```bash finch restart [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for restart -t, --time uint Seconds to wait for stop before killing it (default 10) ``` diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md index 9d79121d5..bed09c443 100644 --- a/docs/cmd/finch_rm.md +++ b/docs/cmd/finch_rm.md @@ -6,13 +6,13 @@ title: "finch rm" Remove one or more containers -``` +```bash finch rm [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) -h, --help help for rm -v, --volumes Remove volumes associated with the container diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md index d38edebdb..3aff10b93 100644 --- a/docs/cmd/finch_rmi.md +++ b/docs/cmd/finch_rmi.md @@ -6,13 +6,13 @@ title: "finch rmi" Remove one or more images -``` +```bash finch rmi [flags] IMAGE [IMAGE, ...] ``` ### Options -``` +```bash --async Asynchronous mode -f, --force Force removal of the image -h, --help help for rmi diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md index af3b6460e..cfa5fd75c 100644 --- a/docs/cmd/finch_run.md +++ b/docs/cmd/finch_run.md @@ -6,13 +6,13 @@ title: "finch run" Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. -``` +```bash finch run [flags] IMAGE [COMMAND] [ARG...] ``` ### Options -``` +```bash --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 diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md index 17ef3bec0..ce6def61c 100644 --- a/docs/cmd/finch_save.md +++ b/docs/cmd/finch_save.md @@ -6,13 +6,13 @@ title: "finch save" The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. -``` +```bash finch save [flags] ``` ### Options -``` +```bash --all-platforms Export content for all platforms -h, --help help for save -o, --output string Write to a file, instead of STDOUT diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md index a9dc69bf5..ad498d03b 100644 --- a/docs/cmd/finch_start.md +++ b/docs/cmd/finch_start.md @@ -6,13 +6,13 @@ title: "finch start" Start one or more running containers -``` +```bash finch start [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -a, --attach Attach STDOUT/STDERR and forward signals --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") -h, --help help for start diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md index 0f92337bf..87b5bb529 100644 --- a/docs/cmd/finch_stats.md +++ b/docs/cmd/finch_stats.md @@ -6,13 +6,13 @@ title: "finch stats" Display a live stream of container(s) resource usage statistics. -``` +```bash finch stats [flags] ``` ### Options -``` +```bash -a, --all Show all containers (default shows just running) --format string Pretty-print images using a Go template, e.g, '{{json .}}' -h, --help help for stats diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md index d54f96ad2..b727d8688 100644 --- a/docs/cmd/finch_stop.md +++ b/docs/cmd/finch_stop.md @@ -6,13 +6,13 @@ title: "finch stop" Stop one or more running containers -``` +```bash finch stop [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for stop -t, --time int Seconds to wait before sending a SIGKILL (default 10) ``` diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md index 353404fb3..dfba58bd6 100644 --- a/docs/cmd/finch_support-bundle_generate.md +++ b/docs/cmd/finch_support-bundle_generate.md @@ -6,13 +6,13 @@ title: "finch support-bundle generate" Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. -``` +```bash finch support-bundle generate [flags] ``` ### Options -``` +```bash --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded -h, --help help for generate --include stringArray additional files to include in the support bundle, specified by absolute or relative path. to include a file from the VM, prefix the file path with "vm:" diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md index c2f120f07..66eb71ffd 100644 --- a/docs/cmd/finch_system.md +++ b/docs/cmd/finch_system.md @@ -6,13 +6,13 @@ title: "finch system" Manage containerd -``` +```bash finch system [flags] ``` ### Commands -``` +```bash events Get real time events from the server info Display system-wide information prune Remove unused data @@ -20,6 +20,6 @@ finch system [flags] ### Options -``` +```bash -h, --help help for system ``` diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md index 2cb4b1934..61583852a 100644 --- a/docs/cmd/finch_tag.md +++ b/docs/cmd/finch_tag.md @@ -6,12 +6,12 @@ title: "finch tag" Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -``` +```bash finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] ``` ### Options -``` +```bash -h, --help help for tag ``` diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md index e2b31d23d..25e2c6f4c 100644 --- a/docs/cmd/finch_top.md +++ b/docs/cmd/finch_top.md @@ -6,12 +6,12 @@ title: "finch top" Display the running processes of a container -``` +```bash finch top CONTAINER [ps OPTIONS] [flags] ``` ### Options -``` +```bash -h, --help help for top ``` diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md index 391ac4d0f..22d6abf61 100644 --- a/docs/cmd/finch_unpause.md +++ b/docs/cmd/finch_unpause.md @@ -6,12 +6,12 @@ title: "finch unpause" Unpause all processes within one or more containers -``` +```bash finch unpause [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for unpause ``` diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md index 1879e3f0f..6eebda17d 100644 --- a/docs/cmd/finch_update.md +++ b/docs/cmd/finch_update.md @@ -6,13 +6,13 @@ title: "finch update" Update one or more running containers -``` +```bash finch update [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md index 39cd9a438..3c8209fed 100644 --- a/docs/cmd/finch_version.md +++ b/docs/cmd/finch_version.md @@ -6,12 +6,12 @@ title: "finch version" Shows Finch version information -``` +```bash finch version [flags] ``` ### Options -``` +```bash -h, --help help for version ``` diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md index e273d160d..0a3e7cbca 100644 --- a/docs/cmd/finch_vm_init.md +++ b/docs/cmd/finch_vm_init.md @@ -6,12 +6,12 @@ title: "finch vm init" Initialize the virtual machine -``` +```bash finch vm init [flags] ``` ### Options -``` +```bash -h, --help help for init ``` diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md index 8423d0239..9a51e9259 100644 --- a/docs/cmd/finch_vm_remove.md +++ b/docs/cmd/finch_vm_remove.md @@ -6,13 +6,13 @@ title: "finch vm remove" Remove the virtual machine instance -``` +```bash finch vm remove [flags] ``` ### Options -``` +```bash -f, --force forcibly remove finch VM -h, --help help for remove ``` diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md index 3fb9bbdbc..e91898dd9 100644 --- a/docs/cmd/finch_vm_start.md +++ b/docs/cmd/finch_vm_start.md @@ -6,12 +6,12 @@ title: "finch vm start" Start the virtual machine -``` +```bash finch vm start [flags] ``` ### Options -``` +```bash -h, --help help for start ``` diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md index 73a46d852..fca8537e9 100644 --- a/docs/cmd/finch_vm_status.md +++ b/docs/cmd/finch_vm_status.md @@ -6,12 +6,12 @@ title: "finch vm status" Status of the virtual machine -``` +```bash finch vm status [flags] ``` ### Options -``` +```bash -h, --help help for status ``` diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md index 7eaed00bf..f71cfcac4 100644 --- a/docs/cmd/finch_vm_stop.md +++ b/docs/cmd/finch_vm_stop.md @@ -6,13 +6,13 @@ title: "finch vm stop" Stop the virtual machine -``` +```bash finch vm stop [flags] ``` ### Options -``` +```bash -f, --force forcibly stop finch VM -h, --help help for stop ``` diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md index 44a22dfe9..ba3a5075d 100644 --- a/docs/cmd/finch_volume.md +++ b/docs/cmd/finch_volume.md @@ -6,13 +6,13 @@ title: "finch volume" Manage volumes -``` +```bash finch volume [flags] ``` ### Commands -``` +```bash create Create a volume inspect Display detailed information on one or more volumes ls List volumes @@ -22,6 +22,6 @@ finch volume [flags] ### Options -``` +```bash -h, --help help for volume ``` diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md index 299a65248..c114628e6 100644 --- a/docs/cmd/finch_wait.md +++ b/docs/cmd/finch_wait.md @@ -6,12 +6,12 @@ title: "finch wait" Block until one or more containers stop, then print their exit codes. -``` +```bash finch wait [flags] CONTAINER [CONTAINER, ...] ``` ### Options -``` +```bash -h, --help help for wait ``` From 136b0e9681b91e472056f3144abf3186fa9ede86 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 13:11:33 -0400 Subject: [PATCH 06/11] fix test Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE | 4 ++-- cmd/finch/gen_docs_test.go | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/cmd/finch/doc.TEMPLATE b/cmd/finch/doc.TEMPLATE index af7477d63..6aa00844f 100644 --- a/cmd/finch/doc.TEMPLATE +++ b/cmd/finch/doc.TEMPLATE @@ -2,9 +2,9 @@ title: "{{ .CmdPath }}" --- -## {{ .CmdPath }}{{if gt (len .Description) 0}} +## {{ .CmdPath }} -{{ .Description }} +{{if gt (len .Description) 0}}{{ .Description }} {{end}}{{if gt (len .Properties) 0}}### Properties diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go index 9429804b0..bf595f735 100644 --- a/cmd/finch/gen_docs_test.go +++ b/cmd/finch/gen_docs_test.go @@ -96,9 +96,10 @@ func TestGenDocsAction_runAdapter(t *testing.T) { require.Equal(t, string(buf), fmt.Sprintf(`--- title: "test-command" --- + ## test-command -%s +%sbash test-command [flags] %s `, codeBlock, codeBlock)) From df42cafdec821a7a04ce62376fcaac2d55560f63 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 19:20:37 -0400 Subject: [PATCH 07/11] remove title and increase header types Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE | 18 +++++++----------- docs/cmd/finch_build.md | 8 ++------ docs/cmd/finch_builder.md | 10 +++------- docs/cmd/finch_commit.md | 8 ++------ docs/cmd/finch_completion_bash.md | 8 ++------ docs/cmd/finch_completion_fish.md | 8 ++------ docs/cmd/finch_completion_powershell.md | 8 ++------ docs/cmd/finch_completion_zsh.md | 8 ++------ docs/cmd/finch_compose.md | 10 +++------- docs/cmd/finch_container.md | 10 +++------- docs/cmd/finch_cp.md | 8 ++------ docs/cmd/finch_create.md | 8 ++------ docs/cmd/finch_events.md | 8 ++------ docs/cmd/finch_exec.md | 8 ++------ docs/cmd/finch_help.md | 8 ++------ docs/cmd/finch_history.md | 8 ++------ docs/cmd/finch_image.md | 10 +++------- docs/cmd/finch_images.md | 10 +++------- docs/cmd/finch_info.md | 8 ++------ docs/cmd/finch_inspect.md | 8 ++------ docs/cmd/finch_kill.md | 8 ++------ docs/cmd/finch_load.md | 8 ++------ docs/cmd/finch_login.md | 8 ++------ docs/cmd/finch_logout.md | 8 ++------ docs/cmd/finch_logs.md | 8 ++------ docs/cmd/finch_network.md | 10 +++------- docs/cmd/finch_pause.md | 8 ++------ docs/cmd/finch_port.md | 8 ++------ docs/cmd/finch_ps.md | 8 ++------ docs/cmd/finch_pull.md | 8 ++------ docs/cmd/finch_push.md | 8 ++------ docs/cmd/finch_restart.md | 8 ++------ docs/cmd/finch_rm.md | 8 ++------ docs/cmd/finch_rmi.md | 8 ++------ docs/cmd/finch_run.md | 8 ++------ docs/cmd/finch_save.md | 8 ++------ docs/cmd/finch_start.md | 8 ++------ docs/cmd/finch_stats.md | 8 ++------ docs/cmd/finch_stop.md | 8 ++------ docs/cmd/finch_support-bundle_generate.md | 8 ++------ docs/cmd/finch_system.md | 10 +++------- docs/cmd/finch_tag.md | 8 ++------ docs/cmd/finch_top.md | 8 ++------ docs/cmd/finch_unpause.md | 8 ++------ docs/cmd/finch_update.md | 8 ++------ docs/cmd/finch_version.md | 8 ++------ docs/cmd/finch_vm_init.md | 8 ++------ docs/cmd/finch_vm_remove.md | 8 ++------ docs/cmd/finch_vm_start.md | 8 ++------ docs/cmd/finch_vm_status.md | 8 ++------ docs/cmd/finch_vm_stop.md | 8 ++------ docs/cmd/finch_volume.md | 10 +++------- docs/cmd/finch_wait.md | 8 ++------ 53 files changed, 119 insertions(+), 331 deletions(-) diff --git a/cmd/finch/doc.TEMPLATE b/cmd/finch/doc.TEMPLATE index 6aa00844f..abd394745 100644 --- a/cmd/finch/doc.TEMPLATE +++ b/cmd/finch/doc.TEMPLATE @@ -1,12 +1,8 @@ ---- -title: "{{ .CmdPath }}" ---- - -## {{ .CmdPath }} +# {{ .CmdPath }} {{if gt (len .Description) 0}}{{ .Description }} -{{end}}{{if gt (len .Properties) 0}}### Properties +{{end}}{{if gt (len .Properties) 0}}## Properties {{.Properties}} @@ -14,29 +10,29 @@ title: "{{ .CmdPath }}" {{ .Usage }} ```{{if gt (len .Aliases) 0}} -### Aliases +## Aliases {{.Aliases}} {{end}}{{if gt (len .Examples) 0}} -### Examples +## Examples {{.Examples}} {{end}}{{if gt (len .Commands) 0}} -### Commands +## Commands ```bash {{ .Commands }} ```{{end}}{{if gt (len .Options) 0}} -### Options +## Options ```bash {{ .Options }} ```{{end}}{{if gt (len .SeeAlso) 0}} -### SEE ALSO +## SEE ALSO {{ .SeeAlso }} {{end}} diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md index d4b4f4127..89f9bfe71 100644 --- a/docs/cmd/finch_build.md +++ b/docs/cmd/finch_build.md @@ -1,8 +1,4 @@ ---- -title: "finch build" ---- - -## finch build +# finch build 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. @@ -11,7 +7,7 @@ If Dockerfile is not present and -f is not specified, it will look for Container finch build [flags] PATH ``` -### Options +## Options ```bash --build-arg stringArray Set build-time variables diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md index 6ab987ee9..f0ac022c2 100644 --- a/docs/cmd/finch_builder.md +++ b/docs/cmd/finch_builder.md @@ -1,8 +1,4 @@ ---- -title: "finch builder" ---- - -## finch builder +# finch builder Manage builds @@ -10,7 +6,7 @@ Manage builds finch builder [flags] ``` -### Commands +## Commands ```bash build Build an image from a Dockerfile. Needs buildkitd to be running. @@ -18,7 +14,7 @@ finch builder [flags] prune Clean up BuildKit build cache ``` -### Options +## Options ```bash -h, --help help for builder diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md index b428685ab..0cc4e557a 100644 --- a/docs/cmd/finch_commit.md +++ b/docs/cmd/finch_commit.md @@ -1,8 +1,4 @@ ---- -title: "finch commit" ---- - -## finch commit +# finch commit Create a new image from a container's changes @@ -10,7 +6,7 @@ Create a new image from a container's changes finch commit [flags] CONTAINER REPOSITORY[:TAG] ``` -### Options +## Options ```bash -a, --author string Author (e.g., "finch contributor ") diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md index a0628e5e9..7fb5e5451 100644 --- a/docs/cmd/finch_completion_bash.md +++ b/docs/cmd/finch_completion_bash.md @@ -1,8 +1,4 @@ ---- -title: "finch completion bash" ---- - -## finch completion bash +# finch completion bash Generate the autocompletion script for the bash shell. @@ -21,7 +17,7 @@ To load completions for every new session, execute once: finch completion bash ``` -### Options +## Options ```bash -h, --help help for bash diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md index d44095316..30e23193f 100644 --- a/docs/cmd/finch_completion_fish.md +++ b/docs/cmd/finch_completion_fish.md @@ -1,8 +1,4 @@ ---- -title: "finch completion fish" ---- - -## finch completion fish +# finch completion fish Generate the autocompletion script for the fish shell. @@ -20,7 +16,7 @@ You will need to start a new shell for this setup to take effect. finch completion fish [flags] ``` -### Options +## Options ```bash -h, --help help for fish diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md index b10191d93..d9c4962f6 100644 --- a/docs/cmd/finch_completion_powershell.md +++ b/docs/cmd/finch_completion_powershell.md @@ -1,8 +1,4 @@ ---- -title: "finch completion powershell" ---- - -## finch completion powershell +# finch completion powershell Generate the autocompletion script for powershell. @@ -17,7 +13,7 @@ to your powershell profile. finch completion powershell [flags] ``` -### Options +## Options ```bash -h, --help help for powershell diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md index e31c7543e..1dcfec26e 100644 --- a/docs/cmd/finch_completion_zsh.md +++ b/docs/cmd/finch_completion_zsh.md @@ -1,8 +1,4 @@ ---- -title: "finch completion zsh" ---- - -## finch completion zsh +# finch completion zsh Generate the autocompletion script for the zsh shell. @@ -23,7 +19,7 @@ To load completions for every new session, execute once: finch completion zsh [flags] ``` -### Options +## Options ```bash -h, --help help for zsh diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md index 52ad52d80..66b5ba895 100644 --- a/docs/cmd/finch_compose.md +++ b/docs/cmd/finch_compose.md @@ -1,8 +1,4 @@ ---- -title: "finch compose" ---- - -## finch compose +# finch compose Compose @@ -10,7 +6,7 @@ Compose finch compose [flags] COMMAND ``` -### Commands +## Commands ```bash build Build or rebuild services @@ -38,7 +34,7 @@ finch compose [flags] COMMAND version Show the Compose version information ``` -### Options +## Options ```bash --env-file string Specify an alternate environment file diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md index 82feb3b66..c77cced57 100644 --- a/docs/cmd/finch_container.md +++ b/docs/cmd/finch_container.md @@ -1,8 +1,4 @@ ---- -title: "finch container" ---- - -## finch container +# finch container Manage containers @@ -10,7 +6,7 @@ Manage containers finch container [flags] ``` -### Commands +## Commands ```bash attach Attach stdin, stdout, and stderr to a running container. @@ -37,7 +33,7 @@ finch container [flags] wait Block until one or more containers stop, then print their exit codes. ``` -### Options +## Options ```bash -h, --help help for container diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md index bc7ce2338..263b2a7de 100644 --- a/docs/cmd/finch_cp.md +++ b/docs/cmd/finch_cp.md @@ -1,8 +1,4 @@ ---- -title: "finch cp" ---- - -## finch cp +# finch cp Copy files/folders between a running container and the local filesystem. This command requires 'tar' to be installed on the host (not in the container). @@ -14,7 +10,7 @@ finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|- finch cp [flags] SRC_PATH|- CONTAINER:DEST_PATH ``` -### Options +## Options ```bash -L, --follow-link Always follow symbolic link in SRC_PATH. diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md index f23b98a95..983ffb89f 100644 --- a/docs/cmd/finch_create.md +++ b/docs/cmd/finch_create.md @@ -1,8 +1,4 @@ ---- -title: "finch create" ---- - -## finch create +# finch create Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,7 +6,7 @@ Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull finch create [flags] IMAGE [COMMAND] [ARG...] ``` -### Options +## Options ```bash --add-host strings Add a custom host-to-IP mapping (host:ip) diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md index c0759bfdf..a0ab9b377 100644 --- a/docs/cmd/finch_events.md +++ b/docs/cmd/finch_events.md @@ -1,8 +1,4 @@ ---- -title: "finch events" ---- - -## finch events +# finch events Get real time events from the server @@ -10,7 +6,7 @@ Get real time events from the server finch events [flags] ``` -### Options +## Options ```bash --format string Format the output using the given Go template, e.g, '{{json .}}' diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md index 4361fef87..3b1493ce4 100644 --- a/docs/cmd/finch_exec.md +++ b/docs/cmd/finch_exec.md @@ -1,8 +1,4 @@ ---- -title: "finch exec" ---- - -## finch exec +# finch exec Run a command in a running container @@ -10,7 +6,7 @@ Run a command in a running container finch exec [flags] CONTAINER COMMAND [ARG...] ``` -### Options +## Options ```bash -d, --detach Detached mode: run command in the background diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md index f8bccccef..04ab36660 100644 --- a/docs/cmd/finch_help.md +++ b/docs/cmd/finch_help.md @@ -1,8 +1,4 @@ ---- -title: "finch help" ---- - -## finch help +# finch help Help provides help for any command in the application. Simply type finch help [path to command] for full details. @@ -11,7 +7,7 @@ Simply type finch help [path to command] for full details. finch help [command] [flags] ``` -### Options +## Options ```bash -h, --help help for help diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md index 6d95253cb..5b3585bd3 100644 --- a/docs/cmd/finch_history.md +++ b/docs/cmd/finch_history.md @@ -1,8 +1,4 @@ ---- -title: "finch history" ---- - -## finch history +# finch history Show the history of an image @@ -10,7 +6,7 @@ Show the history of an image finch history [flags] IMAGE ``` -### Options +## Options ```bash -f, --format string Format the output using the given Go template, e.g, '{{json .}}' diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md index bb4183624..5a81c0ee8 100644 --- a/docs/cmd/finch_image.md +++ b/docs/cmd/finch_image.md @@ -1,8 +1,4 @@ ---- -title: "finch image" ---- - -## finch image +# finch image Manage images @@ -10,7 +6,7 @@ Manage images finch image [flags] ``` -### Commands +## Commands ```bash build Build an image from a Dockerfile. Needs buildkitd to be running. @@ -29,7 +25,7 @@ finch image [flags] tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE ``` -### Options +## Options ```bash -h, --help help for image diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md index 7ec6bace2..bc3117cf6 100644 --- a/docs/cmd/finch_images.md +++ b/docs/cmd/finch_images.md @@ -1,12 +1,8 @@ ---- -title: "finch images" ---- - -## finch images +# finch images List images -### Properties +## Properties - REPOSITORY: Repository - TAG: Tag @@ -21,7 +17,7 @@ List images finch images [flags] [REPOSITORY[:TAG]] ``` -### Options +## Options ```bash -a, --all (unimplemented yet, always true) (default true) diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md index 3334459b4..653cc3e5e 100644 --- a/docs/cmd/finch_info.md +++ b/docs/cmd/finch_info.md @@ -1,8 +1,4 @@ ---- -title: "finch info" ---- - -## finch info +# finch info Display system-wide information @@ -10,7 +6,7 @@ Display system-wide information finch info [flags] ``` -### Options +## Options ```bash -f, --format string Format the output using the given Go template, e.g, '{{json .}}' diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md index 440999d00..f3257e2b3 100644 --- a/docs/cmd/finch_inspect.md +++ b/docs/cmd/finch_inspect.md @@ -1,8 +1,4 @@ ---- -title: "finch inspect" ---- - -## finch inspect +# finch inspect Return low-level information on objects. @@ -10,7 +6,7 @@ Return low-level information on objects. finch inspect [flags] ``` -### Options +## Options ```bash -f, --format string Format the output using the given Go template, e.g, '{{json .}}' diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md index 6b073dbb4..c645333fa 100644 --- a/docs/cmd/finch_kill.md +++ b/docs/cmd/finch_kill.md @@ -1,8 +1,4 @@ ---- -title: "finch kill" ---- - -## finch kill +# finch kill Kill one or more running containers @@ -10,7 +6,7 @@ Kill one or more running containers finch kill [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for kill diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md index 51b18c356..d28f92219 100644 --- a/docs/cmd/finch_load.md +++ b/docs/cmd/finch_load.md @@ -1,8 +1,4 @@ ---- -title: "finch load" ---- - -## finch load +# finch load Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. @@ -10,7 +6,7 @@ Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. finch load [flags] ``` -### Options +## Options ```bash --all-platforms Import content for all platforms diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md index 21383a935..2c5cea091 100644 --- a/docs/cmd/finch_login.md +++ b/docs/cmd/finch_login.md @@ -1,8 +1,4 @@ ---- -title: "finch login" ---- - -## finch login +# finch login Log in to a container registry @@ -10,7 +6,7 @@ Log in to a container registry finch login [flags] [SERVER] ``` -### Options +## Options ```bash -h, --help help for login diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md index 3cb026552..49bb55860 100644 --- a/docs/cmd/finch_logout.md +++ b/docs/cmd/finch_logout.md @@ -1,8 +1,4 @@ ---- -title: "finch logout" ---- - -## finch logout +# finch logout Log out from a container registry @@ -10,7 +6,7 @@ Log out from a container registry finch logout [flags] [SERVER] ``` -### Options +## Options ```bash -h, --help help for logout diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md index 606fdecc0..a5725161b 100644 --- a/docs/cmd/finch_logs.md +++ b/docs/cmd/finch_logs.md @@ -1,8 +1,4 @@ ---- -title: "finch logs" ---- - -## finch logs +# finch logs Fetch the logs of a container. @@ -15,7 +11,7 @@ The following containers are supported: finch logs [flags] CONTAINER ``` -### Options +## Options ```bash -f, --follow Follow log output diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md index 9fbb576f2..e69f7c06a 100644 --- a/docs/cmd/finch_network.md +++ b/docs/cmd/finch_network.md @@ -1,8 +1,4 @@ ---- -title: "finch network" ---- - -## finch network +# finch network Manage networks @@ -10,7 +6,7 @@ Manage networks finch network [flags] ``` -### Commands +## Commands ```bash create Create a network @@ -20,7 +16,7 @@ finch network [flags] rm Remove one or more networks ``` -### Options +## Options ```bash -h, --help help for network diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md index 9096bafd9..d7c0b35e3 100644 --- a/docs/cmd/finch_pause.md +++ b/docs/cmd/finch_pause.md @@ -1,8 +1,4 @@ ---- -title: "finch pause" ---- - -## finch pause +# finch pause Pause all processes within one or more containers @@ -10,7 +6,7 @@ Pause all processes within one or more containers finch pause [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for pause diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md index 2add36cce..cc6382e6e 100644 --- a/docs/cmd/finch_port.md +++ b/docs/cmd/finch_port.md @@ -1,8 +1,4 @@ ---- -title: "finch port" ---- - -## finch port +# finch port List port mappings or a specific mapping for the container @@ -10,7 +6,7 @@ List port mappings or a specific mapping for the container finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] ``` -### Options +## Options ```bash -h, --help help for port diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md index 6886cbeee..076fcb269 100644 --- a/docs/cmd/finch_ps.md +++ b/docs/cmd/finch_ps.md @@ -1,8 +1,4 @@ ---- -title: "finch ps" ---- - -## finch ps +# finch ps List containers @@ -10,7 +6,7 @@ List containers finch ps [flags] ``` -### Options +## Options ```bash -a, --all Show all containers (default shows just running) diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md index 38ef06d89..2d6a7dee9 100644 --- a/docs/cmd/finch_pull.md +++ b/docs/cmd/finch_pull.md @@ -1,8 +1,4 @@ ---- -title: "finch pull" ---- - -## finch pull +# finch pull Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,7 +6,7 @@ Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme finch pull [flags] NAME[:TAG] ``` -### Options +## Options ```bash --all-platforms Pull content for all platforms diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md index 2fca75c2b..7896d8191 100644 --- a/docs/cmd/finch_push.md +++ b/docs/cmd/finch_push.md @@ -1,8 +1,4 @@ ---- -title: "finch push" ---- - -## finch push +# finch push Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. @@ -10,7 +6,7 @@ Push an image or a repository to a registry. Optionally specify "ipfs://" or "ip finch push [flags] NAME[:TAG] ``` -### Options +## Options ```bash --all-platforms Push content for all platforms diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md index 3d48d02d4..d2a78d56d 100644 --- a/docs/cmd/finch_restart.md +++ b/docs/cmd/finch_restart.md @@ -1,8 +1,4 @@ ---- -title: "finch restart" ---- - -## finch restart +# finch restart Restart one or more running containers @@ -10,7 +6,7 @@ Restart one or more running containers finch restart [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for restart diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md index bed09c443..9404ae1b3 100644 --- a/docs/cmd/finch_rm.md +++ b/docs/cmd/finch_rm.md @@ -1,8 +1,4 @@ ---- -title: "finch rm" ---- - -## finch rm +# finch rm Remove one or more containers @@ -10,7 +6,7 @@ Remove one or more containers finch rm [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md index 3aff10b93..3e04f6308 100644 --- a/docs/cmd/finch_rmi.md +++ b/docs/cmd/finch_rmi.md @@ -1,8 +1,4 @@ ---- -title: "finch rmi" ---- - -## finch rmi +# finch rmi Remove one or more images @@ -10,7 +6,7 @@ Remove one or more images finch rmi [flags] IMAGE [IMAGE, ...] ``` -### Options +## Options ```bash --async Asynchronous mode diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md index cfa5fd75c..859471167 100644 --- a/docs/cmd/finch_run.md +++ b/docs/cmd/finch_run.md @@ -1,8 +1,4 @@ ---- -title: "finch run" ---- - -## finch run +# finch run Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. @@ -10,7 +6,7 @@ Run a command in a new container. Optionally specify "ipfs://" or "ipns://" sche finch run [flags] IMAGE [COMMAND] [ARG...] ``` -### Options +## Options ```bash --add-host strings Add a custom host-to-IP mapping (host:ip) diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md index ce6def61c..088a20c2e 100644 --- a/docs/cmd/finch_save.md +++ b/docs/cmd/finch_save.md @@ -1,8 +1,4 @@ ---- -title: "finch save" ---- - -## finch save +# finch save The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. @@ -10,7 +6,7 @@ The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. finch save [flags] ``` -### Options +## Options ```bash --all-platforms Export content for all platforms diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md index ad498d03b..f1eb11d87 100644 --- a/docs/cmd/finch_start.md +++ b/docs/cmd/finch_start.md @@ -1,8 +1,4 @@ ---- -title: "finch start" ---- - -## finch start +# finch start Start one or more running containers @@ -10,7 +6,7 @@ Start one or more running containers finch start [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -a, --attach Attach STDOUT/STDERR and forward signals diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md index 87b5bb529..b4717ca88 100644 --- a/docs/cmd/finch_stats.md +++ b/docs/cmd/finch_stats.md @@ -1,8 +1,4 @@ ---- -title: "finch stats" ---- - -## finch stats +# finch stats Display a live stream of container(s) resource usage statistics. @@ -10,7 +6,7 @@ Display a live stream of container(s) resource usage statistics. finch stats [flags] ``` -### Options +## Options ```bash -a, --all Show all containers (default shows just running) diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md index b727d8688..bdde5d9f5 100644 --- a/docs/cmd/finch_stop.md +++ b/docs/cmd/finch_stop.md @@ -1,8 +1,4 @@ ---- -title: "finch stop" ---- - -## finch stop +# finch stop Stop one or more running containers @@ -10,7 +6,7 @@ Stop one or more running containers finch stop [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for stop diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md index dfba58bd6..a3bc64567 100644 --- a/docs/cmd/finch_support-bundle_generate.md +++ b/docs/cmd/finch_support-bundle_generate.md @@ -1,8 +1,4 @@ ---- -title: "finch support-bundle generate" ---- - -## finch support-bundle generate +# finch support-bundle generate Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. @@ -10,7 +6,7 @@ Generates a collection of logs and configs that can be uploaded to a Github issu finch support-bundle generate [flags] ``` -### Options +## Options ```bash --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md index 66eb71ffd..303cf84a6 100644 --- a/docs/cmd/finch_system.md +++ b/docs/cmd/finch_system.md @@ -1,8 +1,4 @@ ---- -title: "finch system" ---- - -## finch system +# finch system Manage containerd @@ -10,7 +6,7 @@ Manage containerd finch system [flags] ``` -### Commands +## Commands ```bash events Get real time events from the server @@ -18,7 +14,7 @@ finch system [flags] prune Remove unused data ``` -### Options +## Options ```bash -h, --help help for system diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md index 61583852a..5498d99b4 100644 --- a/docs/cmd/finch_tag.md +++ b/docs/cmd/finch_tag.md @@ -1,8 +1,4 @@ ---- -title: "finch tag" ---- - -## finch tag +# finch tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE @@ -10,7 +6,7 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] ``` -### Options +## Options ```bash -h, --help help for tag diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md index 25e2c6f4c..76cdf59be 100644 --- a/docs/cmd/finch_top.md +++ b/docs/cmd/finch_top.md @@ -1,8 +1,4 @@ ---- -title: "finch top" ---- - -## finch top +# finch top Display the running processes of a container @@ -10,7 +6,7 @@ Display the running processes of a container finch top CONTAINER [ps OPTIONS] [flags] ``` -### Options +## Options ```bash -h, --help help for top diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md index 22d6abf61..aa7de0fb0 100644 --- a/docs/cmd/finch_unpause.md +++ b/docs/cmd/finch_unpause.md @@ -1,8 +1,4 @@ ---- -title: "finch unpause" ---- - -## finch unpause +# finch unpause Unpause all processes within one or more containers @@ -10,7 +6,7 @@ Unpause all processes within one or more containers finch unpause [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for unpause diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md index 6eebda17d..e8b996ec9 100644 --- a/docs/cmd/finch_update.md +++ b/docs/cmd/finch_update.md @@ -1,8 +1,4 @@ ---- -title: "finch update" ---- - -## finch update +# finch update Update one or more running containers @@ -10,7 +6,7 @@ Update one or more running containers finch update [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md index 3c8209fed..154242727 100644 --- a/docs/cmd/finch_version.md +++ b/docs/cmd/finch_version.md @@ -1,8 +1,4 @@ ---- -title: "finch version" ---- - -## finch version +# finch version Shows Finch version information @@ -10,7 +6,7 @@ Shows Finch version information finch version [flags] ``` -### Options +## Options ```bash -h, --help help for version diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md index 0a3e7cbca..d63487076 100644 --- a/docs/cmd/finch_vm_init.md +++ b/docs/cmd/finch_vm_init.md @@ -1,8 +1,4 @@ ---- -title: "finch vm init" ---- - -## finch vm init +# finch vm init Initialize the virtual machine @@ -10,7 +6,7 @@ Initialize the virtual machine finch vm init [flags] ``` -### Options +## Options ```bash -h, --help help for init diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md index 9a51e9259..7c384faba 100644 --- a/docs/cmd/finch_vm_remove.md +++ b/docs/cmd/finch_vm_remove.md @@ -1,8 +1,4 @@ ---- -title: "finch vm remove" ---- - -## finch vm remove +# finch vm remove Remove the virtual machine instance @@ -10,7 +6,7 @@ Remove the virtual machine instance finch vm remove [flags] ``` -### Options +## Options ```bash -f, --force forcibly remove finch VM diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md index e91898dd9..1a348c35f 100644 --- a/docs/cmd/finch_vm_start.md +++ b/docs/cmd/finch_vm_start.md @@ -1,8 +1,4 @@ ---- -title: "finch vm start" ---- - -## finch vm start +# finch vm start Start the virtual machine @@ -10,7 +6,7 @@ Start the virtual machine finch vm start [flags] ``` -### Options +## Options ```bash -h, --help help for start diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md index fca8537e9..fcc58586a 100644 --- a/docs/cmd/finch_vm_status.md +++ b/docs/cmd/finch_vm_status.md @@ -1,8 +1,4 @@ ---- -title: "finch vm status" ---- - -## finch vm status +# finch vm status Status of the virtual machine @@ -10,7 +6,7 @@ Status of the virtual machine finch vm status [flags] ``` -### Options +## Options ```bash -h, --help help for status diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md index f71cfcac4..d355c3e00 100644 --- a/docs/cmd/finch_vm_stop.md +++ b/docs/cmd/finch_vm_stop.md @@ -1,8 +1,4 @@ ---- -title: "finch vm stop" ---- - -## finch vm stop +# finch vm stop Stop the virtual machine @@ -10,7 +6,7 @@ Stop the virtual machine finch vm stop [flags] ``` -### Options +## Options ```bash -f, --force forcibly stop finch VM diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md index ba3a5075d..72c50ff1b 100644 --- a/docs/cmd/finch_volume.md +++ b/docs/cmd/finch_volume.md @@ -1,8 +1,4 @@ ---- -title: "finch volume" ---- - -## finch volume +# finch volume Manage volumes @@ -10,7 +6,7 @@ Manage volumes finch volume [flags] ``` -### Commands +## Commands ```bash create Create a volume @@ -20,7 +16,7 @@ finch volume [flags] rm Remove one or more volumes ``` -### Options +## Options ```bash -h, --help help for volume diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md index c114628e6..ed51d42dc 100644 --- a/docs/cmd/finch_wait.md +++ b/docs/cmd/finch_wait.md @@ -1,8 +1,4 @@ ---- -title: "finch wait" ---- - -## finch wait +# finch wait Block until one or more containers stop, then print their exit codes. @@ -10,7 +6,7 @@ Block until one or more containers stop, then print their exit codes. finch wait [flags] CONTAINER [CONTAINER, ...] ``` -### Options +## Options ```bash -h, --help help for wait From f727624397452c873f10bf494da4c9f26ccd519c Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 19:28:42 -0400 Subject: [PATCH 08/11] update test Signed-off-by: Justin Alvarez --- cmd/finch/gen_docs_test.go | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go index bf595f735..69a3021f0 100644 --- a/cmd/finch/gen_docs_test.go +++ b/cmd/finch/gen_docs_test.go @@ -93,11 +93,7 @@ func TestGenDocsAction_runAdapter(t *testing.T) { postRunCheck: func(t *testing.T, fs afero.Fs) { buf, err := afero.ReadFile(fs, "outDir/test-command.md") require.NoError(t, err) - require.Equal(t, string(buf), fmt.Sprintf(`--- -title: "test-command" ---- - -## test-command + require.Equal(t, string(buf), fmt.Sprintf(`## test-command %sbash test-command [flags] From 3d28c465668c7524b35ae829e94e030de7013351 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Fri, 20 Oct 2023 19:32:41 -0400 Subject: [PATCH 09/11] fix test header level Signed-off-by: Justin Alvarez --- cmd/finch/gen_docs_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go index 69a3021f0..9f4668860 100644 --- a/cmd/finch/gen_docs_test.go +++ b/cmd/finch/gen_docs_test.go @@ -93,7 +93,7 @@ func TestGenDocsAction_runAdapter(t *testing.T) { postRunCheck: func(t *testing.T, fs afero.Fs) { buf, err := afero.ReadFile(fs, "outDir/test-command.md") require.NoError(t, err) - require.Equal(t, string(buf), fmt.Sprintf(`## test-command + require.Equal(t, string(buf), fmt.Sprintf(`# test-command %sbash test-command [flags] From f965e9e820d91752fb01d660a090abe76ed12c68 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Mon, 23 Oct 2023 18:52:56 -0400 Subject: [PATCH 10/11] wrap errors, add example and update markdown code langauge Signed-off-by: Justin Alvarez --- cmd/finch/doc.TEMPLATE | 6 +++--- cmd/finch/gen_docs.go | 6 +++++- cmd/finch/gen_docs_test.go | 2 +- docs/cmd/finch_build.md | 4 ++-- docs/cmd/finch_builder.md | 6 +++--- docs/cmd/finch_commit.md | 4 ++-- docs/cmd/finch_completion_bash.md | 4 ++-- docs/cmd/finch_completion_fish.md | 4 ++-- docs/cmd/finch_completion_powershell.md | 4 ++-- docs/cmd/finch_completion_zsh.md | 4 ++-- docs/cmd/finch_compose.md | 6 +++--- docs/cmd/finch_container.md | 6 +++--- docs/cmd/finch_cp.md | 4 ++-- docs/cmd/finch_create.md | 4 ++-- docs/cmd/finch_events.md | 4 ++-- docs/cmd/finch_exec.md | 4 ++-- docs/cmd/finch_help.md | 4 ++-- docs/cmd/finch_history.md | 4 ++-- docs/cmd/finch_image.md | 6 +++--- docs/cmd/finch_images.md | 4 ++-- docs/cmd/finch_info.md | 4 ++-- docs/cmd/finch_inspect.md | 4 ++-- docs/cmd/finch_kill.md | 4 ++-- docs/cmd/finch_load.md | 4 ++-- docs/cmd/finch_login.md | 4 ++-- docs/cmd/finch_logout.md | 4 ++-- docs/cmd/finch_logs.md | 4 ++-- docs/cmd/finch_network.md | 6 +++--- docs/cmd/finch_pause.md | 4 ++-- docs/cmd/finch_port.md | 4 ++-- docs/cmd/finch_ps.md | 4 ++-- docs/cmd/finch_pull.md | 4 ++-- docs/cmd/finch_push.md | 4 ++-- docs/cmd/finch_restart.md | 4 ++-- docs/cmd/finch_rm.md | 4 ++-- docs/cmd/finch_rmi.md | 4 ++-- docs/cmd/finch_run.md | 4 ++-- docs/cmd/finch_save.md | 4 ++-- docs/cmd/finch_start.md | 4 ++-- docs/cmd/finch_stats.md | 4 ++-- docs/cmd/finch_stop.md | 4 ++-- docs/cmd/finch_support-bundle_generate.md | 4 ++-- docs/cmd/finch_system.md | 6 +++--- docs/cmd/finch_tag.md | 4 ++-- docs/cmd/finch_top.md | 4 ++-- docs/cmd/finch_unpause.md | 4 ++-- docs/cmd/finch_update.md | 4 ++-- docs/cmd/finch_version.md | 4 ++-- docs/cmd/finch_vm_init.md | 4 ++-- docs/cmd/finch_vm_remove.md | 4 ++-- docs/cmd/finch_vm_start.md | 4 ++-- docs/cmd/finch_vm_status.md | 4 ++-- docs/cmd/finch_vm_stop.md | 4 ++-- docs/cmd/finch_volume.md | 6 +++--- docs/cmd/finch_wait.md | 4 ++-- 55 files changed, 120 insertions(+), 116 deletions(-) diff --git a/cmd/finch/doc.TEMPLATE b/cmd/finch/doc.TEMPLATE index abd394745..9a0c7c264 100644 --- a/cmd/finch/doc.TEMPLATE +++ b/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}} diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go index d6d7f9f73..4aa0f9330 100644 --- a/cmd/finch/gen_docs.go +++ b/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() diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go index 9f4668860..5d5905127 100644 --- a/cmd/finch/gen_docs_test.go +++ b/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)) diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md index 89f9bfe71..02213dfa7 100644 --- a/docs/cmd/finch_build.md +++ b/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) diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md index f0ac022c2..f184efa3e 100644 --- a/docs/cmd/finch_builder.md +++ b/docs/cmd/finch_builder.md @@ -2,13 +2,13 @@ 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 @@ -16,6 +16,6 @@ finch builder [flags] ## Options -```bash +```text -h, --help help for builder ``` diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md index 0cc4e557a..a1af07dcc 100644 --- a/docs/cmd/finch_commit.md +++ b/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 ") -c, --change stringArray Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) -h, --help help for commit diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md index 7fb5e5451..f23daf008 100644 --- a/docs/cmd/finch_completion_bash.md +++ b/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 ``` diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md index 30e23193f..7bd00d9f9 100644 --- a/docs/cmd/finch_completion_fish.md +++ b/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 ``` diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md index d9c4962f6..2665ec6b4 100644 --- a/docs/cmd/finch_completion_powershell.md +++ b/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 ``` diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md index 1dcfec26e..0ad834d53 100644 --- a/docs/cmd/finch_completion_zsh.md +++ b/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 ``` diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md index 66b5ba895..1b6925380 100644 --- a/docs/cmd/finch_compose.md +++ b/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 diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md index c77cced57..3aa6daa16 100644 --- a/docs/cmd/finch_container.md +++ b/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 ``` diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md index 263b2a7de..cc82dfb55 100644 --- a/docs/cmd/finch_cp.md +++ b/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 ``` diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md index 983ffb89f..8aabc79f6 100644 --- a/docs/cmd/finch_create.md +++ b/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 diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md index a0ab9b377..e061afcf3 100644 --- a/docs/cmd/finch_events.md +++ b/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 ``` diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md index 3b1493ce4..d5f3c09b9 100644 --- a/docs/cmd/finch_exec.md +++ b/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 diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md index 04ab36660..f70168002 100644 --- a/docs/cmd/finch_help.md +++ b/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 ``` diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md index 5b3585bd3..a7be4cfb6 100644 --- a/docs/cmd/finch_history.md +++ b/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 diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md index 5a81c0ee8..65463aa1f 100644 --- a/docs/cmd/finch_image.md +++ b/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 ``` diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md index bc3117cf6..e8afd62d5 100644 --- a/docs/cmd/finch_images.md +++ b/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 diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md index 653cc3e5e..d86ec8cb8 100644 --- a/docs/cmd/finch_info.md +++ b/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") diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md index f3257e2b3..758a4177a 100644 --- a/docs/cmd/finch_inspect.md +++ b/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") diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md index c645333fa..536fcc44c 100644 --- a/docs/cmd/finch_kill.md +++ b/docs/cmd/finch_kill.md @@ -2,13 +2,13 @@ Kill one or more running containers -```bash +```text finch kill [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for kill -s, --signal string Signal to send to the container (default "KILL") ``` diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md index d28f92219..d60dfc636 100644 --- a/docs/cmd/finch_load.md +++ b/docs/cmd/finch_load.md @@ -2,13 +2,13 @@ Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. -```bash +```text finch load [flags] ``` ## Options -```bash +```text --all-platforms Import content for all platforms -h, --help help for load -i, --input string Read from tar archive file, instead of STDIN diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md index 2c5cea091..d8ca14965 100644 --- a/docs/cmd/finch_login.md +++ b/docs/cmd/finch_login.md @@ -2,13 +2,13 @@ Log in to a container registry -```bash +```text finch login [flags] [SERVER] ``` ## Options -```bash +```text -h, --help help for login -p, --password string Password --password-stdin Take the password from stdin diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md index 49bb55860..39346977c 100644 --- a/docs/cmd/finch_logout.md +++ b/docs/cmd/finch_logout.md @@ -2,12 +2,12 @@ Log out from a container registry -```bash +```text finch logout [flags] [SERVER] ``` ## Options -```bash +```text -h, --help help for logout ``` diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md index a5725161b..39efc2773 100644 --- a/docs/cmd/finch_logs.md +++ b/docs/cmd/finch_logs.md @@ -7,13 +7,13 @@ The following containers are supported: - Containers created with 'finch compose'. - Containers created with Kubernetes (EXPERIMENTAL). -```bash +```text finch logs [flags] CONTAINER ``` ## Options -```bash +```text -f, --follow Follow log output -h, --help help for logs --since string Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md index e69f7c06a..1fb3b0415 100644 --- a/docs/cmd/finch_network.md +++ b/docs/cmd/finch_network.md @@ -2,13 +2,13 @@ Manage networks -```bash +```text finch network [flags] ``` ## Commands -```bash +```text create Create a network inspect Display detailed information on one or more networks ls List networks @@ -18,6 +18,6 @@ finch network [flags] ## Options -```bash +```text -h, --help help for network ``` diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md index d7c0b35e3..13231d848 100644 --- a/docs/cmd/finch_pause.md +++ b/docs/cmd/finch_pause.md @@ -2,12 +2,12 @@ Pause all processes within one or more containers -```bash +```text finch pause [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for pause ``` diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md index cc6382e6e..94ba2d781 100644 --- a/docs/cmd/finch_port.md +++ b/docs/cmd/finch_port.md @@ -2,12 +2,12 @@ List port mappings or a specific mapping for the container -```bash +```text finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] ``` ## Options -```bash +```text -h, --help help for port ``` diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md index 076fcb269..a4dda03dd 100644 --- a/docs/cmd/finch_ps.md +++ b/docs/cmd/finch_ps.md @@ -2,13 +2,13 @@ List containers -```bash +```text finch ps [flags] ``` ## Options -```bash +```text -a, --all Show all containers (default shows just running) -f, --filter strings Filter matches containers based on given conditions --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md index 2d6a7dee9..7c5b0366b 100644 --- a/docs/cmd/finch_pull.md +++ b/docs/cmd/finch_pull.md @@ -2,13 +2,13 @@ Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. -```bash +```text finch pull [flags] NAME[:TAG] ``` ## Options -```bash +```text --all-platforms Pull content for all platforms --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md index 7896d8191..e2ba4a661 100644 --- a/docs/cmd/finch_push.md +++ b/docs/cmd/finch_push.md @@ -2,13 +2,13 @@ Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. -```bash +```text finch push [flags] NAME[:TAG] ``` ## Options -```bash +```text --all-platforms Push content for all platforms --allow-nondistributable-artifacts Allow pushing images with non-distributable blobs --cosign-key string Path to the private key file, KMS URI or Kubernetes Secret for --sign=cosign diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md index d2a78d56d..78881a81a 100644 --- a/docs/cmd/finch_restart.md +++ b/docs/cmd/finch_restart.md @@ -2,13 +2,13 @@ Restart one or more running containers -```bash +```text finch restart [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for restart -t, --time uint Seconds to wait for stop before killing it (default 10) ``` diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md index 9404ae1b3..a99986707 100644 --- a/docs/cmd/finch_rm.md +++ b/docs/cmd/finch_rm.md @@ -2,13 +2,13 @@ Remove one or more containers -```bash +```text finch rm [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) -h, --help help for rm -v, --volumes Remove volumes associated with the container diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md index 3e04f6308..a9e6bbad0 100644 --- a/docs/cmd/finch_rmi.md +++ b/docs/cmd/finch_rmi.md @@ -2,13 +2,13 @@ Remove one or more images -```bash +```text finch rmi [flags] IMAGE [IMAGE, ...] ``` ## Options -```bash +```text --async Asynchronous mode -f, --force Force removal of the image -h, --help help for rmi diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md index 859471167..79f004e8a 100644 --- a/docs/cmd/finch_run.md +++ b/docs/cmd/finch_run.md @@ -2,13 +2,13 @@ Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. -```bash +```text finch run [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 diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md index 088a20c2e..15e78e4b4 100644 --- a/docs/cmd/finch_save.md +++ b/docs/cmd/finch_save.md @@ -2,13 +2,13 @@ The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. -```bash +```text finch save [flags] ``` ## Options -```bash +```text --all-platforms Export content for all platforms -h, --help help for save -o, --output string Write to a file, instead of STDOUT diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md index f1eb11d87..fa70a3ea2 100644 --- a/docs/cmd/finch_start.md +++ b/docs/cmd/finch_start.md @@ -2,13 +2,13 @@ Start one or more running containers -```bash +```text finch start [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -a, --attach Attach STDOUT/STDERR and forward signals --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") -h, --help help for start diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md index b4717ca88..93b8c8bfb 100644 --- a/docs/cmd/finch_stats.md +++ b/docs/cmd/finch_stats.md @@ -2,13 +2,13 @@ Display a live stream of container(s) resource usage statistics. -```bash +```text finch stats [flags] ``` ## Options -```bash +```text -a, --all Show all containers (default shows just running) --format string Pretty-print images using a Go template, e.g, '{{json .}}' -h, --help help for stats diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md index bdde5d9f5..5800177f3 100644 --- a/docs/cmd/finch_stop.md +++ b/docs/cmd/finch_stop.md @@ -2,13 +2,13 @@ Stop one or more running containers -```bash +```text finch stop [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for stop -t, --time int Seconds to wait before sending a SIGKILL (default 10) ``` diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md index a3bc64567..e2974168f 100644 --- a/docs/cmd/finch_support-bundle_generate.md +++ b/docs/cmd/finch_support-bundle_generate.md @@ -2,13 +2,13 @@ Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. -```bash +```text finch support-bundle generate [flags] ``` ## Options -```bash +```text --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded -h, --help help for generate --include stringArray additional files to include in the support bundle, specified by absolute or relative path. to include a file from the VM, prefix the file path with "vm:" diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md index 303cf84a6..30783bc2b 100644 --- a/docs/cmd/finch_system.md +++ b/docs/cmd/finch_system.md @@ -2,13 +2,13 @@ Manage containerd -```bash +```text finch system [flags] ``` ## Commands -```bash +```text events Get real time events from the server info Display system-wide information prune Remove unused data @@ -16,6 +16,6 @@ finch system [flags] ## Options -```bash +```text -h, --help help for system ``` diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md index 5498d99b4..9afa9abbc 100644 --- a/docs/cmd/finch_tag.md +++ b/docs/cmd/finch_tag.md @@ -2,12 +2,12 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -```bash +```text finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] ``` ## Options -```bash +```text -h, --help help for tag ``` diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md index 76cdf59be..207800903 100644 --- a/docs/cmd/finch_top.md +++ b/docs/cmd/finch_top.md @@ -2,12 +2,12 @@ Display the running processes of a container -```bash +```text finch top CONTAINER [ps OPTIONS] [flags] ``` ## Options -```bash +```text -h, --help help for top ``` diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md index aa7de0fb0..3ed37619a 100644 --- a/docs/cmd/finch_unpause.md +++ b/docs/cmd/finch_unpause.md @@ -2,12 +2,12 @@ Unpause all processes within one or more containers -```bash +```text finch unpause [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for unpause ``` diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md index e8b996ec9..829df1317 100644 --- a/docs/cmd/finch_update.md +++ b/docs/cmd/finch_update.md @@ -2,13 +2,13 @@ Update one or more running containers -```bash +```text finch update [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md index 154242727..9f18cd88f 100644 --- a/docs/cmd/finch_version.md +++ b/docs/cmd/finch_version.md @@ -2,12 +2,12 @@ Shows Finch version information -```bash +```text finch version [flags] ``` ## Options -```bash +```text -h, --help help for version ``` diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md index d63487076..00e3e5093 100644 --- a/docs/cmd/finch_vm_init.md +++ b/docs/cmd/finch_vm_init.md @@ -2,12 +2,12 @@ Initialize the virtual machine -```bash +```text finch vm init [flags] ``` ## Options -```bash +```text -h, --help help for init ``` diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md index 7c384faba..d027de487 100644 --- a/docs/cmd/finch_vm_remove.md +++ b/docs/cmd/finch_vm_remove.md @@ -2,13 +2,13 @@ Remove the virtual machine instance -```bash +```text finch vm remove [flags] ``` ## Options -```bash +```text -f, --force forcibly remove finch VM -h, --help help for remove ``` diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md index 1a348c35f..720e24ca1 100644 --- a/docs/cmd/finch_vm_start.md +++ b/docs/cmd/finch_vm_start.md @@ -2,12 +2,12 @@ Start the virtual machine -```bash +```text finch vm start [flags] ``` ## Options -```bash +```text -h, --help help for start ``` diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md index fcc58586a..ef43aef59 100644 --- a/docs/cmd/finch_vm_status.md +++ b/docs/cmd/finch_vm_status.md @@ -2,12 +2,12 @@ Status of the virtual machine -```bash +```text finch vm status [flags] ``` ## Options -```bash +```text -h, --help help for status ``` diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md index d355c3e00..4ea379834 100644 --- a/docs/cmd/finch_vm_stop.md +++ b/docs/cmd/finch_vm_stop.md @@ -2,13 +2,13 @@ Stop the virtual machine -```bash +```text finch vm stop [flags] ``` ## Options -```bash +```text -f, --force forcibly stop finch VM -h, --help help for stop ``` diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md index 72c50ff1b..bd79abcc4 100644 --- a/docs/cmd/finch_volume.md +++ b/docs/cmd/finch_volume.md @@ -2,13 +2,13 @@ Manage volumes -```bash +```text finch volume [flags] ``` ## Commands -```bash +```text create Create a volume inspect Display detailed information on one or more volumes ls List volumes @@ -18,6 +18,6 @@ finch volume [flags] ## Options -```bash +```text -h, --help help for volume ``` diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md index ed51d42dc..fb5af58a8 100644 --- a/docs/cmd/finch_wait.md +++ b/docs/cmd/finch_wait.md @@ -2,12 +2,12 @@ Block until one or more containers stop, then print their exit codes. -```bash +```text finch wait [flags] CONTAINER [CONTAINER, ...] ``` ## Options -```bash +```text -h, --help help for wait ``` From 567988b844ea7dfba05fed0893df06c57cb6a234 Mon Sep 17 00:00:00 2001 From: Justin Alvarez Date: Mon, 23 Oct 2023 19:20:37 -0400 Subject: [PATCH 11/11] update main_test comment to be more generic Signed-off-by: Justin Alvarez --- cmd/finch/main_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/finch/main_test.go b/cmd/finch/main_test.go index 0dc61db00..0b03c5e9e 100644 --- a/cmd/finch/main_test.go +++ b/cmd/finch/main_test.go @@ -138,7 +138,7 @@ func TestNewApp(t *testing.T) { assert.Equal(t, cmd.Version, version.Version) assert.Equal(t, cmd.SilenceUsage, true) assert.Equal(t, cmd.SilenceErrors, true) - // confirm the number of command, comprised of nerdctl commands + finch commands (version, vm, support-bundle) + // confirm the number of command, comprised of nerdctl commands + finch commands assert.Equal(t, len(cmd.Commands()), len(nerdctlCmds)+4) // PersistentPreRunE should set logger level to debug if the debug flag exists.