Better documentation generation

pkg/yqlib/operator_equals_test.go

@@ -6,22 +6,25 @@ import (
 
 var equalsOperatorScenarios = []expressionScenario{
 	{
-		document:   `[cat,goat,dog]`,
+		description: "Match string",
-		expression: `.[] | (. == "*at")`,
+		document:    `[cat,goat,dog]`,
+		expression:  `.[] | (. == "*at")`,
 		expected: []string{
 			"D0, P[0], (!!bool)::true\n",
 			"D0, P[1], (!!bool)::true\n",
 			"D0, P[2], (!!bool)::false\n",
 		},
 	}, {
-		document:   `[3, 4, 5]`,
+		description: "Match number",
-		expression: `.[] | (. == 4)`,
+		document:    `[3, 4, 5]`,
+		expression:  `.[] | (. == 4)`,
 		expected: []string{
 			"D0, P[0], (!!bool)::false\n",
 			"D0, P[1], (!!bool)::true\n",
 			"D0, P[2], (!!bool)::false\n",
 		},
 	}, {
+		skipDoc:    true,
 		document:   `a: { cat: {b: apple, c: whatever}, pat: {b: banana} }`,
 		expression: `.a | (.[].b == "apple")`,
 		expected: []string{
@@ -30,6 +33,7 @@ var equalsOperatorScenarios = []expressionScenario{
 		},
 	},
 	{
+		skipDoc:    true,
 		document:   ``,
 		expression: `null == null`,
 		expected: []string{
@@ -37,8 +41,9 @@ var equalsOperatorScenarios = []expressionScenario{
 		},
 	},
 	{
-		document:   ``,
+		description: "Match nulls",
-		expression: `null == ~`,
+		document:    ``,
+		expression:  `null == ~`,
 		expected: []string{
 			"D0, P[], (!!bool)::true\n",
 		},

pkg/yqlib/operators_test.go

@@ -5,6 +5,7 @@ import (
 	"bytes"
 	"container/list"
 	"fmt"
+	"io"
 	"os"
 	"strings"
 	"testing"
@@ -55,35 +56,61 @@ func writeOrPanic(w *bufio.Writer, text string) {
 	}
 }
 
+func copyFromHeader(title string, out *os.File) (bool, error) {
+	source := fmt.Sprintf("doc/headers/%v.md", title)
+	_, err := os.Stat(source)
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	in, err := os.Open(source) // nolint gosec
+	if err != nil {
+		return false, err
+	}
+	defer safelyCloseFile(in)
+	_, err = io.Copy(out, in)
+	return true, err
+}
+
 func documentScenarios(t *testing.T, title string, scenarios []expressionScenario) {
 	f, err := os.Create(fmt.Sprintf("doc/%v.md", title))
 
 	if err != nil {
 		t.Error(err)
+		return
 	}
 	defer f.Close()
+
+	hasHeader, err := copyFromHeader(title, f)
+	if err != nil {
+		t.Error(err)
+		return
+	}
+
 	w := bufio.NewWriter(f)
-	writeOrPanic(w, fmt.Sprintf("# %v\n", title))
+
-	writeOrPanic(w, "## Examples\n")
+	if !hasHeader {
+		writeOrPanic(w, fmt.Sprintf("## %v\n", title))
+	}
 
 	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 != "" {
-				writeOrPanic(w, "sample.yml:\n")
+				//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, "Expression\n")
+				writeOrPanic(w, "then\n")
 				writeOrPanic(w, fmt.Sprintf("```bash\nyq '%v' < sample.yml\n```\n", s.expression))
 			}
 
-			writeOrPanic(w, "Result\n")
+			writeOrPanic(w, "will output\n")
 
 			var output bytes.Buffer
 			var err error

pkg/yqlib/utils.go

@@ -151,23 +151,23 @@ func EvaluateFileStreamsSequence(expression string, filenames []string, printer
 // 	}
 // }
 
-// // thanks https://stackoverflow.com/questions/21060945/simple-way-to-copy-a-file-in-golang
+// thanks https://stackoverflow.com/questions/21060945/simple-way-to-copy-a-file-in-golang
-// func copyFileContents(src, dst string) (err error) {
+func copyFileContents(src, dst string) (err error) {
-// 	in, err := os.Open(src) // nolint gosec
+	in, err := os.Open(src) // nolint gosec
-// 	if err != nil {
+	if err != nil {
-// 		return err
+		return err
-// 	}
+	}
-// 	defer safelyCloseFile(in)
+	defer safelyCloseFile(in)
-// 	out, err := os.Create(dst)
+	out, err := os.Create(dst)
-// 	if err != nil {
+	if err != nil {
-// 		return err
+		return err
-// 	}
+	}
-// 	defer safelyCloseFile(out)
+	defer safelyCloseFile(out)
-// 	if _, err = io.Copy(out, in); err != nil {
+	if _, err = io.Copy(out, in); err != nil {
-// 		return err
+		return err
-// 	}
+	}
-// 	return out.Sync()
+	return out.Sync()
-// }
+}
 
 func safelyFlush(writer *bufio.Writer) {
 	if err := writer.Flush(); err != nil {