feat: add pagination and searching to atmos docs command (#848)

* feat: add pagination and search to docs command

* docs: update documentation with pagination settings

* fix: cleanup documentation and capitalization

---------

Co-authored-by: Andriy Knysh <[email protected]>

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
 		}
 

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 {

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
+}

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
     ```
 </File>
 
@@ -171,9 +178,21 @@ The `settings` section configures Atmos global settings.
       <dd>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.</dd>
     </dl>
   </dd>
-</dl>
+
+  <dt>`settings.docs`</dt>
+  <dd>
+    Specifies how component documentation is displayed in the terminal.
 
+    The following settings are supported:
+    <dl>
+      <dt>`max-width`</dt>
+      <dd>The maximum width for displaying component documentation in the terminal.</dd>
 
+      <dt>`pagination`</dt>
+      <dd>When enabled, displays component documentation in a pager instead of directly in the terminal.</dd>
+    </dl>
+  </dd>
+</dl>
 
 ## Workflows