diff --git a/cmd/docs.go b/cmd/docs.go index 547cd018a..129e58591 100644 --- a/cmd/docs.go +++ b/cmd/docs.go @@ -97,7 +97,10 @@ var docsCmd = &cobra.Command{ u.LogErrorAndExit(schema.CliConfiguration{}, err) } - fmt.Println(componentDocs) + if err := u.DisplayDocs(componentDocs, cliConfig.Settings.Docs.Pagination); err != nil { + u.LogErrorAndExit(schema.CliConfiguration{}, fmt.Errorf("failed to display documentation: %w", err)) + } + return } diff --git a/pkg/schema/schema.go b/pkg/schema/schema.go index 7eacc76ff..ff05ed6dc 100644 --- a/pkg/schema/schema.go +++ b/pkg/schema/schema.go @@ -34,7 +34,8 @@ type CliSettings struct { } type Docs struct { - MaxWidth int `yaml:"max-width" json:"max_width" mapstructure:"max-width"` + MaxWidth int `yaml:"max-width" json:"max_width" mapstructure:"max-width"` + Pagination bool `yaml:"pagination" json:"pagination" mapstructure:"pagination"` } type Templates struct { diff --git a/pkg/utils/doc_utils.go b/pkg/utils/doc_utils.go new file mode 100644 index 000000000..a8d302acc --- /dev/null +++ b/pkg/utils/doc_utils.go @@ -0,0 +1,39 @@ +package utils + +import ( + "fmt" + "os" + "os/exec" + "strings" +) + +// DisplayDocs displays component documentation directly through the terminal or +// through a pager (like less). The use of a pager is determined by the pagination value +// set in the CLI Settings for Atmos +func DisplayDocs(componentDocs string, usePager bool) error { + if !usePager { + fmt.Println(componentDocs) + return nil + } + + pagerCmd := os.Getenv("PAGER") + if pagerCmd == "" { + pagerCmd = "less -r" + } + + args := strings.Fields(pagerCmd) + if len(args) == 0 { + return fmt.Errorf("invalid pager command") + } + + cmd := exec.Command(args[0], args[1:]...) + cmd.Stdin = strings.NewReader(componentDocs) + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + + if err := cmd.Run(); err != nil { + return fmt.Errorf("failed to execute pager: %w", err) + } + + return nil +} diff --git a/website/docs/cli/configuration/configuration.mdx b/website/docs/cli/configuration/configuration.mdx index bcc4761e7..4e95a6850 100644 --- a/website/docs/cli/configuration/configuration.mdx +++ b/website/docs/cli/configuration/configuration.mdx @@ -151,6 +151,13 @@ The `settings` section configures Atmos global settings. # If the source and destination lists have the same length, all items in the destination lists are # deep-merged with all items in the source list. list_merge_strategy: replace + # `docs` specifies how component documentation is displayed in the terminal. + # The following documentation display settings are supported: + # `max-width`: The maximum width for displaying component documentation in the terminal. + # 'pagination`: When enabled, displays component documentation in a pager instead of directly in the terminal. + docs: + max-width: 80 + pagination: true ``` @@ -171,9 +178,21 @@ The `settings` section configures Atmos global settings.