fix: Doc generate - Escape pipe symbols in output enums in md (#476)

This then guarantees the generated markdown cells align properly.

Signed-off-by: Mihai Galos <[email protected]>

Author: mihaigalos

pkg/tools/gen/escape.go

@@ -0,0 +1,44 @@
+package gen
+
+import "strings"
+
+func DeepEscapePipesInPackage(pkg *KclPackage) *KclPackage {
+	if pkg == nil {
+		return nil
+	}
+	escaped := &KclPackage{
+		Name:           pkg.Name,
+		Version:        pkg.Version,
+		Description:    pkg.Description,
+		SchemaList:     nil,
+		SubPackageList: nil,
+	}
+
+	if pkg.SchemaList != nil {
+		escaped.SchemaList = make([]*KclOpenAPIType, len(pkg.SchemaList))
+		for i, schema := range pkg.SchemaList {
+			escaped.SchemaList[i] = deepEscapePipesInSchema(schema)
+		}
+	}
+	if pkg.SubPackageList != nil {
+		escaped.SubPackageList = make([]*KclPackage, len(pkg.SubPackageList))
+		for i, sub := range pkg.SubPackageList {
+			escaped.SubPackageList[i] = DeepEscapePipesInPackage(sub)
+		}
+	}
+	return escaped
+}
+
+func deepEscapePipesInSchema(schema *KclOpenAPIType) *KclOpenAPIType {
+	if schema == nil {
+		return nil
+	}
+	escaped := *schema
+	if schema.Enum != nil {
+		escaped.Enum = make([]string, len(schema.Enum))
+		for i, v := range schema.Enum {
+			escaped.Enum[i] = strings.ReplaceAll(v, "|", "\\|")
+		}
+	}
+	return &escaped
+}

pkg/tools/gen/gendoc.go

@@ -282,13 +282,17 @@ func (g *GenContext) renderPackage(spec *SwaggerV2Spec, parentDir string) error
 	switch strings.ToLower(string(g.Format)) {
 	case string(Markdown):
 		docFileName := fmt.Sprintf("%s.%s", pkgName, g.Format)
+
+		// Escape pipe symbols in all string fields of the package before templating
+		escapedPkg := DeepEscapePipesInPackage(pkg)
+
 		var buf bytes.Buffer
 		err := g.Template.ExecuteTemplate(&buf, "packageDoc", struct {
 			EscapeHtml bool
 			Data       *KclPackage
 		}{
 			EscapeHtml: g.EscapeHtml,
-			Data:       pkg,
+			Data:       escapedPkg,
 		})
 		if err != nil {
 			return fmt.Errorf("failed to render package %s with template, err: %s", pkg.Name, err)

pkg/tools/gen/gendoc_test.go

@@ -4,11 +4,12 @@ import (
 	"bufio"
 	"errors"
 	"fmt"
-	assert2 "github.com/stretchr/testify/assert"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	assert2 "github.com/stretchr/testify/assert"
 )
 
 func TestIndexContent(t *testing.T) {
@@ -249,3 +250,17 @@ func readLines(path string) ([]string, error) {
 	}
 	return lines, scanner.Err()
 }
+
+func TestDeepEscapePipesInSchema_EnumPipeEscaping(t *testing.T) {
+	schema := &KclOpenAPIType{
+		Enum: []string{"A|B", "C", "D|E|F"},
+	}
+
+	escaped := deepEscapePipesInSchema(schema)
+
+	assert2.Equal(t, []string{"A\\|B", "C", "D\\|E\\|F"}, escaped.Enum)
+	assert2.Equal(t, schema.Default, escaped.Default)
+	assert2.Equal(t, schema.Description, escaped.Description)
+	assert2.Equal(t, schema.ExternalDocs, escaped.ExternalDocs)
+	assert2.Equal(t, schema.Ref, escaped.Ref)
+}