DOCS: TypeScript updates (#2402)

build/generate/dtsFile.go

@@ -1,10 +1,14 @@
 package main
 
 import (
+	"fmt"
 	"os"
+	"path"
 	"strings"
 )
 
+var commentStart = "@dnscontrol-auto-doc-comment "
+
 func generateDTSFile(funcs string) error {
 	names := []string{
 		"base-types",
@@ -20,9 +24,50 @@ func generateDTSFile(funcs string) error {
 		if err != nil {
 			return err
 		}
+		// Find all instances of `/** @dnscontrol-auto-doc-comment <path> */`
+		// and replace them with the contents of the file at <path>.
+		// This allows us to keep the documentation in the same file as the code.
+		for {
+			start := strings.Index(string(content), commentStart)
+			if start == -1 {
+				break
+			}
+			end := strings.Index(string(content[start:]), "\n")
+			if end == -1 {
+				return fmt.Errorf("unterminated @dnscontrol-auto-doc-comment in '%s'", name)
+			}
+
+			docPath := string(content[start+len(commentStart) : start+end])
+			println("Replacing", docPath)
+
+			if strings.Contains(docPath, "..") {
+				return fmt.Errorf("invalid path '%s' in '%s'", docPath, name)
+			}
+
+			newPath := path.Clean(join("documentation", docPath))
+			if !strings.HasPrefix(newPath, "documentation") {
+				return fmt.Errorf("invalid path '%s' in '%s'", docPath, name)
+			}
+			_, body, err := readDocFile(newPath)
+			if err != nil {
+				return err
+			}
+
+			body = strings.ReplaceAll(strings.Trim(body, "\n"), "\n", "\n * ")
+
+			content = append(content[:start], append([]byte(body), content[start+end:]...)...)
+		}
+
 		combined = append(combined, string(content))
 	}
 	combined = append(combined, funcs)
-	os.WriteFile(join("commands", "types", "dnscontrol.d.ts"), []byte(strings.Join(combined, "\n\n")), 0644)
+	fileContent := strings.Join(combined, "\n\n")
+	lines := strings.Split(fileContent, "\n")
+	fileContent = ""
+	for _, line := range lines {
+		fileContent += strings.TrimRight(line, " \t") + "\n"
+	}
+	fileContent = strings.TrimRight(fileContent, "\n")
+	os.WriteFile(join("commands", "types", "dnscontrol.d.ts"), []byte(fileContent+"\n"), 0644)
 	return nil
 }

build/generate/functionTypes.go

@@ -16,6 +16,7 @@ func join(parts ...string) string {
 	return strings.Join(parts, string(os.PathSeparator))
 }
 
+// removes repeated blank lines, replacing them with a single blank line.
 func fixRuns(s string) string {
 	lines := strings.Split(s, "\n")
 	var out []string
@@ -32,6 +33,33 @@ func fixRuns(s string) string {
 
 var delimiterRegex = regexp.MustCompile(`(?m)^---\n`)
 
+func readDocFile(fPath string) (map[string]interface{}, string, error) {
+	content, err := os.ReadFile(fPath)
+	if err != nil {
+		return nil, "", err
+	}
+	frontMatter, body, err := parseFrontMatter(string(content))
+	if err != nil {
+		return nil, "", err
+	}
+
+	lines := strings.Split(body, "\n")
+
+	body = ""
+
+	for _, line := range lines {
+		if strings.HasPrefix(line, "{%") && strings.HasSuffix(line, "%}") {
+			continue
+		}
+		body += line + "\n"
+	}
+
+	body = strings.ReplaceAll(body, "**NOTE**", "NOTE")
+	body = strings.ReplaceAll(body, "**WARNING**", "WARNING")
+	body = fixRuns(body)
+	return frontMatter, body, nil
+}
+
 func parseFrontMatter(content string) (map[string]interface{}, string, error) {
 	delimiterIndices := delimiterRegex.FindAllStringIndex(content, 2)
 	if len(delimiterIndices) < 1 {
@@ -93,32 +121,16 @@ func generateFunctionTypes() (string, error) {
 				return "", errors.New("not a file: " + fPath)
 			}
 			// println("Processing", fPath)
-			content, err := os.ReadFile(fPath)
-			if err != nil {
-				return "", err
-			}
-			frontMatter, body, err := parseFrontMatter(string(content))
+			frontMatter, body, err := readDocFile(fPath)
 			if err != nil {
 				println("Error parsing front matter in", fPath, "error: ", err.Error())
 				continue
+
 			}
 			if frontMatter["ts_ignore"] == true {
 				continue
 			}
 
-			lines := strings.Split(body, "\n")
-			body = ""
-			for _, line := range lines {
-				if strings.HasPrefix(line, "{%") && strings.HasSuffix(line, "%}") {
-					continue
-				}
-				body += line + "\n"
-			}
-
-			body = strings.ReplaceAll(body, "**NOTE**", "NOTE")
-			body = strings.ReplaceAll(body, "**WARNING**", "WARNING")
-			body = fixRuns(body)
-
 			paramNames := []string{}
 			if frontMatter["parameters"] != nil {
 				for _, p := range frontMatter["parameters"].([]interface{}) {