From d91b25840ad972bbeba36ec5a45b3090f3c4ad73 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 13 Nov 2020 21:22:05 +1100
Subject: [PATCH] Better documentation generation

---
 pkg/yqlib/operator_collect_test.go | 33 +++++++++++++-------
 pkg/yqlib/operators_test.go        | 49 +++++++++++++++++++++---------
 pkg/yqlib/utils.go                 | 32 +++++++++----------
 3 files changed, 72 insertions(+), 42 deletions(-)

diff --git a/pkg/yqlib/operator_collect_test.go b/pkg/yqlib/operator_collect_test.go
index 0f2501f..26f075d 100644
--- a/pkg/yqlib/operator_collect_test.go
+++ b/pkg/yqlib/operator_collect_test.go
@@ -6,43 +6,54 @@ import (
 
 var collectOperatorScenarios = []expressionScenario{
 	{
-		document:   ``,
-		expression: `[]`,
-		expected:   []string{},
+		description: "Collect empty",
+		document:    ``,
+		expression:  `[]`,
+		expected:    []string{},
 	},
 	{
-		document:   ``,
-		expression: `["cat"]`,
+		description: "Collect single",
+		document:    ``,
+		expression:  `["cat"]`,
 		expected: []string{
 			"D0, P[], (!!seq)::- cat\n",
 		},
 	}, {
 		document:   ``,
+		skipDoc:    true,
 		expression: `[true]`,
 		expected: []string{
 			"D0, P[], (!!seq)::- true\n",
 		},
-	}, {
-		document:   ``,
-		expression: `["cat", "dog"]`,
+	},
+	{
+		description: "Collect many",
+		document:    `{a: cat, b: dog}`,
+		expression:  `[.a, .b]`,
 		expected: []string{
 			"D0, P[], (!!seq)::- cat\n- dog\n",
 		},
-	}, {
+	},
+	{
 		document:   ``,
+		skipDoc:    true,
 		expression: `1 | collect`,
 		expected: []string{
 			"D0, P[], (!!seq)::- 1\n",
 		},
-	}, {
+	},
+	{
 		document:   `[1,2,3]`,
+		skipDoc:    true,
 		expression: `[.[]]`,
 		expected: []string{
 			"D0, P[], (!!seq)::- 1\n- 2\n- 3\n",
 		},
-	}, {
+	},
+	{
 		document:   `a: {b: [1,2,3]}`,
 		expression: `[.a.b[]]`,
+		skipDoc:    true,
 		expected: []string{
 			"D0, P[a b], (!!seq)::- 1\n- 2\n- 3\n",
 		},
diff --git a/pkg/yqlib/operators_test.go b/pkg/yqlib/operators_test.go
index ce7e99e..ff2700f 100644
--- a/pkg/yqlib/operators_test.go
+++ b/pkg/yqlib/operators_test.go
@@ -56,19 +56,34 @@ func writeOrPanic(w *bufio.Writer, text string) {
 	}
 }
 
-func copyFromHeader(title string, out *os.File) (bool, error) {
+func copyFromHeader(title string, out *os.File) error {
 	source := fmt.Sprintf("doc/headers/%v.md", title)
 	_, err := os.Stat(source)
 	if os.IsNotExist(err) {
-		return false, nil
+		return nil
 	}
 	in, err := os.Open(source) // nolint gosec
 	if err != nil {
-		return false, err
+		return err
 	}
 	defer safelyCloseFile(in)
 	_, err = io.Copy(out, in)
-	return true, err
+	return err
+}
+
+func formatYaml(yaml string) string {
+	var output bytes.Buffer
+	printer := NewPrinter(bufio.NewWriter(&output), false, true, false, 2, true)
+
+	node, err := treeCreator.ParsePath(".. style= \"\"")
+	if err != nil {
+		panic(err)
+	}
+	err = EvaluateStream("sample.yaml", strings.NewReader(yaml), node, printer)
+	if err != nil {
+		panic(err)
+	}
+	return output.String()
 }
 
 func documentScenarios(t *testing.T, title string, scenarios []expressionScenario) {
@@ -80,7 +95,7 @@ func documentScenarios(t *testing.T, title string, scenarios []expressionScenari
 	}
 	defer f.Close()
 
-	hasHeader, err := copyFromHeader(title, f)
+	err = copyFromHeader(title, f)
 	if err != nil {
 		t.Error(err)
 		return
@@ -88,26 +103,30 @@ func documentScenarios(t *testing.T, title string, scenarios []expressionScenari
 
 	w := bufio.NewWriter(f)
 
-	if !hasHeader {
-		writeOrPanic(w, fmt.Sprintf("## %v\n", title))
-	}
+	writeOrPanic(w, "## Examples\n")
 
 	for index, s := range scenarios {
 		if !s.skipDoc {
 
 			if s.description != "" {
-				writeOrPanic(w, fmt.Sprintf("## %v\n", s.description))
+				writeOrPanic(w, fmt.Sprintf("### %v\n", s.description))
 			} else {
-				writeOrPanic(w, fmt.Sprintf("## Example %v\n", index))
+				writeOrPanic(w, fmt.Sprintf("### Example %v\n", index))
 			}
 			if s.document != "" {
 				//TODO: pretty here
 				writeOrPanic(w, "Given a sample.yml file of:\n")
-				writeOrPanic(w, fmt.Sprintf("```yaml\n%v\n```\n", s.document))
-			}
-			if s.expression != "" {
+
+				writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n", formatYaml(s.document)))
 				writeOrPanic(w, "then\n")
-				writeOrPanic(w, fmt.Sprintf("```bash\nyq '%v' < sample.yml\n```\n", s.expression))
+				if s.expression != "" {
+					writeOrPanic(w, fmt.Sprintf("```bash\nyq eval '%v' sample.yml\n```\n", s.expression))
+				} else {
+					writeOrPanic(w, "```bash\nyq eval sample.yml\n```\n")
+				}
+			} else {
+				writeOrPanic(w, "Running\n")
+				writeOrPanic(w, fmt.Sprintf("```bash\nyq eval --null-input '%v'\n```\n", s.expression))
 			}
 
 			writeOrPanic(w, "will output\n")
@@ -132,7 +151,7 @@ func documentScenarios(t *testing.T, title string, scenarios []expressionScenari
 				}
 			}
 
-			writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n", output.String()))
+			writeOrPanic(w, fmt.Sprintf("```yaml\n%v```\n\n", output.String()))
 
 		}
 
diff --git a/pkg/yqlib/utils.go b/pkg/yqlib/utils.go
index ba8f684..3b7360b 100644
--- a/pkg/yqlib/utils.go
+++ b/pkg/yqlib/utils.go
@@ -152,22 +152,22 @@ func EvaluateFileStreamsSequence(expression string, filenames []string, printer
 // }
 
 // thanks https://stackoverflow.com/questions/21060945/simple-way-to-copy-a-file-in-golang
-func copyFileContents(src, dst string) (err error) {
-	in, err := os.Open(src) // nolint gosec
-	if err != nil {
-		return err
-	}
-	defer safelyCloseFile(in)
-	out, err := os.Create(dst)
-	if err != nil {
-		return err
-	}
-	defer safelyCloseFile(out)
-	if _, err = io.Copy(out, in); err != nil {
-		return err
-	}
-	return out.Sync()
-}
+// func copyFileContents(src, dst string) (err error) {
+// 	in, err := os.Open(src) // nolint gosec
+// 	if err != nil {
+// 		return err
+// 	}
+// 	defer safelyCloseFile(in)
+// 	out, err := os.Create(dst)
+// 	if err != nil {
+// 		return err
+// 	}
+// 	defer safelyCloseFile(out)
+// 	if _, err = io.Copy(out, in); err != nil {
+// 		return err
+// 	}
+// 	return out.Sync()
+// }
 
 func safelyFlush(writer *bufio.Writer) {
 	if err := writer.Flush(); err != nil {