Adapt docsgen output for new documentation framework (#2262)

## Changes

Update `docsgen` output to align with new documentation framework

1. New header style, previously we had brackets for `<name>`, now it's
in italic `_name_`
2. Updated broken markdown in OpenAPI descriptions
3. Table markdown has different structure in new framework

## Tests

Updated existing tests

NO_CHANGELOG=true

bundle/docsgen/main.go

@@ -7,6 +7,7 @@ import (
 	"path"
 	"reflect"
 	"strings"
+	"time"
 
 	"github.com/databricks/cli/bundle/config"
 	"github.com/databricks/cli/bundle/internal/annotation"
@@ -43,7 +44,7 @@ func main() {
 		[]string{path.Join(annotationDir, "annotations.yml")},
 		path.Join(outputDir, rootFileName),
 		reflect.TypeOf(config.Root{}),
-		string(rootHeader),
+		fillTemplateVariables(string(rootHeader)),
 	)
 	if err != nil {
 		log.Fatal(err)
@@ -56,7 +57,7 @@ func main() {
 		[]string{path.Join(annotationDir, "annotations_openapi.yml"), path.Join(annotationDir, "annotations_openapi_overrides.yml"), path.Join(annotationDir, "annotations.yml")},
 		path.Join(outputDir, resourcesFileName),
 		reflect.TypeOf(config.Resources{}),
-		string(resourcesHeader),
+		fillTemplateVariables(string(resourcesHeader)),
 	)
 	if err != nil {
 		log.Fatal(err)
@@ -133,3 +134,8 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 		s.Examples = []string{a.MarkdownExamples}
 	}
 }
+
+func fillTemplateVariables(s string) string {
+	currentDate := time.Now().Format("2006-01-02")
+	return strings.ReplaceAll(s, "{{update_date}}", currentDate)
+}

bundle/docsgen/markdown.go

@@ -12,7 +12,7 @@ func buildMarkdown(nodes []rootNode, outputFile, header string) error {
 	m = m.PlainText(header)
 	for _, node := range nodes {
 		m = m.LF()
-		title := escapeBrackets(node.Title)
+		title := node.Title
 		if node.TopLevel {
 			m = m.H2(title)
 		} else {
@@ -68,21 +68,24 @@ func pickLastWord(s string) string {
 // Build a custom table which we use in Databricks website
 func buildAttributeTable(m *markdownRenderer, attributes []attributeNode) *markdownRenderer {
 	m = m.LF()
-	m = m.PlainText(".. list-table::")
-	m = m.PlainText("   :header-rows: 1")
+	m = m.PlainText(":::list-table")
 	m = m.LF()
 
-	m = m.PlainText("   * - Key")
-	m = m.PlainText("     - Type")
-	m = m.PlainText("     - Description")
+	m = m.PlainText("- - Key")
+	m = m.PlainText("  - Type")
+	m = m.PlainText("  - Description")
 	m = m.LF()
 
 	for _, a := range attributes {
-		m = m.PlainText("   * - " + fmt.Sprintf("`%s`", a.Title))
-		m = m.PlainText("     - " + a.Type)
-		m = m.PlainText("     - " + formatDescription(a))
+		m = m.PlainText("- - " + fmt.Sprintf("`%s`", a.Title))
+		m = m.PlainText("  - " + a.Type)
+		m = m.PlainText("  - " + formatDescription(a))
 		m = m.LF()
 	}
+
+	m = m.PlainText(":::")
+	m = m.LF()
+
 	return m
 }
 
@@ -94,23 +97,15 @@ func formatDescription(a attributeNode) string {
 		} else if s != "" {
 			s += ". "
 		}
-		s += fmt.Sprintf("See [_](#%s).", cleanAnchor(a.Link))
+		s += fmt.Sprintf("See [\\_](#%s).", cleanAnchor(a.Link))
 	}
 	return s
 }
 
 // Docs framework does not allow special characters in anchor links and strip them out by default
 // We need to clean them up to make sure the links pass the validation
 func cleanAnchor(s string) string {
-	s = strings.ReplaceAll(s, "<", "")
-	s = strings.ReplaceAll(s, ">", "")
 	s = strings.ReplaceAll(s, ".", "")
-
-	return s
-}
-
-func escapeBrackets(s string) string {
-	s = strings.ReplaceAll(s, "<", "\\<")
-	s = strings.ReplaceAll(s, ">", "\\>")
+	s = strings.ReplaceAll(s, nameFieldWithFormat, nameField)
 	return s
 }

bundle/docsgen/markdown_test.go

@@ -20,12 +20,12 @@ func TestBuildMarkdownAnchors(t *testing.T) {
 					Title:       "my_attribute",
 					Type:        "Map",
 					Description: "Desc with link",
-					Link:        "some_field.<name>.my_attribute",
+					Link:        "some_field._name_.my_attribute",
 				},
 			},
 		},
 		{
-			Title:       "some_field.<name>.my_attribute",
+			Title:       "some_field._name_.my_attribute",
 			TopLevel:    false,
 			Type:        "Boolean",
 			Description: "Another description",

bundle/docsgen/nodes.go

@@ -137,8 +137,13 @@ func getMapValueType(v *jsonschema.Schema, refs map[string]*jsonschema.Schema) *
 	return nil
 }
 
+const (
+	nameField           = "name"
+	nameFieldWithFormat = "_name_"
+)
+
 func getMapKeyPrefix(s string) string {
-	return s + ".<name>"
+	return s + "." + nameFieldWithFormat
 }
 
 func removePluralForm(s string) string {

bundle/docsgen/nodes_test.go

@@ -93,11 +93,11 @@ func TestBuildNodes_ChildExpansion(t *testing.T) {
 					TopLevel: true,
 					Type:     "Map",
 					ObjectKeyAttributes: []attributeNode{
-						{Title: "mapSub", Type: "Map", Link: "myMap.<name>.mapSub"},
+						{Title: "mapSub", Type: "Map", Link: "myMap._name_.mapSub"},
 					},
 				},
 				{
-					Title: "myMap.<name>.mapSub",
+					Title: "myMap._name_.mapSub",
 					Type:  "Map",
 					Attributes: []attributeNode{
 						{Title: "deepSub", Type: "Boolean"},