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.
The items in the destination list are deep-merged with the items in the source list. The items in the source list take precedence. The items are processed starting from the first up to the length of the source list (the remaining items are not processed). 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.
- + +
`settings.docs`
+
+ Specifies how component documentation is displayed in the terminal. + The following 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.
+
+
+ ## Workflows