From 682c4bd2cbdb3974e7b43e70e28fb54d2d0f349f Mon Sep 17 00:00:00 2001
From: RoseSecurity <michaeljrosenfeld22@gmail.com>
Date: Thu, 12 Dec 2024 11:25:59 -0500
Subject: [PATCH 1/3] feat: add pagination and search to docs command

---
 cmd/docs.go            |  5 ++++-
 pkg/schema/schema.go   |  3 ++-
 pkg/utils/doc_utils.go | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 pkg/utils/doc_utils.go

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..cf88e7def
--- /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
+}

From 4f1877f4d763689f3528185e1fda7759a3173e06 Mon Sep 17 00:00:00 2001
From: RoseSecurity <michaeljrosenfeld22@gmail.com>
Date: Thu, 12 Dec 2024 11:37:05 -0500
Subject: [PATCH 2/3] docs: update documentation with pagination settings

---
 .../docs/cli/configuration/configuration.mdx  | 21 ++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

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
     ```
 </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
 

From ee3f3b0754738246014700701f0a091cfca44317 Mon Sep 17 00:00:00 2001
From: RoseSecurity <michaeljrosenfeld22@gmail.com>
Date: Thu, 12 Dec 2024 11:41:32 -0500
Subject: [PATCH 3/3] fix: cleanup documentation and capitalization

---
 pkg/utils/doc_utils.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkg/utils/doc_utils.go b/pkg/utils/doc_utils.go
index cf88e7def..a8d302acc 100644
--- a/pkg/utils/doc_utils.go
+++ b/pkg/utils/doc_utils.go
@@ -7,7 +7,7 @@ import (
 	"strings"
 )
 
-// displayDocs displays component documentation directly through the terminal or
+// 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 {