feat: Add examples to the docs

bundle/internal/docs/docs.go

@@ -50,6 +50,7 @@ func getNodes(s jsonschema.Schema, refs map[string]jsonschema.Schema, customFiel
 			Title:       k,
 			Description: getDescription(v, item.topLevel),
 			TopLevel:    item.topLevel,
+			Example:     getExample(v),
 		}
 
 		node.Attributes = getAttributes(v.Properties, refs)
@@ -80,6 +81,15 @@ func getNodes(s jsonschema.Schema, refs map[string]jsonschema.Schema, customFiel
 	return nodes
 }
 
+const header = `---
+description: Configuration reference for databricks.yml
+---
+
+# Configuration reference
+
+This article provides reference for keys supported by <DABS> configuration (YAML). See [\_](/dev-tools/bundles/index.md).
+`
+
 func buildMarkdown(nodes []rootNode, outputFile string) error {
 	f, err := os.Create(outputFile)
 	if err != nil {
@@ -88,6 +98,7 @@ func buildMarkdown(nodes []rootNode, outputFile string) error {
 	defer f.Close()
 
 	m := md.NewMarkdown(f)
+	m = m.PlainText(header)
 	for _, node := range nodes {
 		m = m.LF()
 		if node.TopLevel {
@@ -111,10 +122,16 @@ func buildMarkdown(nodes []rootNode, outputFile string) error {
 			m = m.LF()
 			m = buildAttributeTable(m, node.ArrayItemAttributes)
 		} else if len(node.Attributes) > 0 {
-			// m = m.H4("Attributes")
 			m = m.LF()
 			m = buildAttributeTable(m, node.Attributes)
 		}
+
+		if node.Example != "" {
+			m = m.LF()
+			m = m.H3("Example")
+			m = m.LF()
+			m = m.PlainText(node.Example)
+		}
 	}
 
 	err = m.Build()
@@ -204,6 +221,7 @@ func resolveRefs(s *jsonschema.Schema, schemas map[string]jsonschema.Schema) *js
 
 	description := s.Description
 	markdownDescription := s.MarkdownDescription
+	examples := s.Examples
 
 	for node.Reference != nil {
 		ref := strings.TrimPrefix(*node.Reference, "#/$defs/")
@@ -218,12 +236,16 @@ func resolveRefs(s *jsonschema.Schema, schemas map[string]jsonschema.Schema) *js
 		if markdownDescription == "" {
 			markdownDescription = newNode.MarkdownDescription
 		}
+		if len(examples) == 0 {
+			examples = newNode.Examples
+		}
 
 		node = &newNode
 	}
 
 	node.Description = description
 	node.MarkdownDescription = markdownDescription
+	node.Examples = examples
 
 	return node
 }
@@ -247,3 +269,11 @@ func extractNodes(prefix string, props map[string]*jsonschema.Schema, refs map[s
 	}
 	return nodes
 }
+
+func getExample(v *jsonschema.Schema) string {
+	examples := v.Examples
+	if len(examples) == 0 {
+		return ""
+	}
+	return examples[0].(string)
+}

bundle/internal/docs/docs.md

@@ -1,3 +1,11 @@
+---
+description: Configuration reference for databricks.yml
+---
+
+# Configuration reference
+
+This article provides reference for keys supported by <DABS> configuration (YAML). See [\_](/dev-tools/bundles/index.md).
+
   
 ## artifacts
   
@@ -46,6 +54,16 @@ Each item has the following attributes:
      - The type of the artifact. Valid values are `wheel` or `jar`
   
   
+### Example
+  
+```yaml
+artifacts:
+  default:
+    type: whl
+    build: poetry build
+    path: .
+```
+  
 ## bundle
   
 The attributes of the bundle. See [_](/dev-tools/bundles/settings.md#bundle)
@@ -246,6 +264,18 @@ Each item of `permissions` has the following attributes:
      - The name of the user that has the permission set in level.
   
   
+### Example
+  
+```yaml
+permissions:
+  - level: CAN_VIEW
+    group_name: test-group
+  - level: CAN_MANAGE
+    user_name: someone@example.com
+  - level: CAN_RUN
+    service_principal_name: 123456-abcdef
+```
+  
 ## presets
   
 Defines bundle deployment presets. See [_](/dev-tools/bundles/deployment-modes.md#presets).

bundle/internal/docs/main.go

@@ -87,6 +87,7 @@ type annotation struct {
 	Title               string `json:"title,omitempty"`
 	Default             any    `json:"default,omitempty"`
 	Enum                []any  `json:"enum,omitempty"`
+	MarkdownExamples    string `json:"markdown_examples,omitempty"`
 }
 
 func generateDocs(workdir, outputPath string) error {
@@ -157,6 +158,9 @@ func assignAnnotation(s *jsonschema.Schema, a annotation) {
 	if a.MarkdownDescription != "" {
 		s.MarkdownDescription = a.MarkdownDescription
 	}
+	if a.MarkdownExamples != "" {
+		s.Examples = []any{a.MarkdownExamples}
+	}
 }
 
 func LoadAndMergeAnnotations(sources []string) (annotationFile, error) {

bundle/internal/schema/annotations.go

@@ -24,6 +24,7 @@ type annotation struct {
 	Title               string `json:"title,omitempty"`
 	Default             any    `json:"default,omitempty"`
 	Enum                []any  `json:"enum,omitempty"`
+	MarkdownExamples    string `json:"markdown_examples,omitempty"`
 }
 
 type annotationHandler struct {

bundle/internal/schema/annotations.yml

@@ -183,6 +183,14 @@ github.com/databricks/cli/bundle/config.Root:
   "artifacts":
     "description": |-
       Defines the attributes to build an artifact
+    "markdown_examples": |-
+      ```yaml
+      artifacts:
+        default:
+          type: whl
+          build: poetry build
+          path: .
+      ```
   "bundle":
     "description": |-
       The attributes of the bundle.
@@ -201,6 +209,16 @@ github.com/databricks/cli/bundle/config.Root:
       Defines the permissions to apply to experiments, jobs, pipelines, and models defined in the bundle
     "markdown_description": |-
       Defines the permissions to apply to experiments, jobs, pipelines, and models defined in the bundle. See [_](/dev-tools/bundles/settings.md#permissions) and [_](/dev-tools/bundles/permissions.md).
+    "markdown_examples": |-
+      ```yaml
+      permissions:
+        - level: CAN_VIEW
+          group_name: test-group
+        - level: CAN_MANAGE
+          user_name: someone@example.com
+        - level: CAN_RUN
+          service_principal_name: 123456-abcdef
+      ```
   "presets":
     "description": |-
       Defines bundle deployment presets.
@@ -445,8 +463,8 @@ github.com/databricks/databricks-sdk-go/service/serving.Ai21LabsConfig:
   "ai21labs_api_key_plaintext":
     "description": |-
       PLACEHOLDER
-github.com/databricks/databricks-sdk-go/service/serving.GoogleCloudVertexAiConfig:
+? github.com/databricks/databricks-sdk-go/service/serving.GoogleCloudVertexAiConfig
-  "private_key":
+: "private_key":
     "description": |-
       PLACEHOLDER
   "private_key_plaintext":

libs/jsonschema/schema.go

@@ -76,6 +76,10 @@ type Schema struct {
 	// Title of the object, rendered as inline documentation in the IDE.
 	// https://json-schema.org/understanding-json-schema/reference/annotations
 	Title string `json:"title,omitempty"`
+
+	// Examples of the value for properties in the schema.
+	// https://json-schema.org/understanding-json-schema/reference/annotations
+	Examples []any `json:"examples,omitempty"`
 }
 
 // Default value defined in a JSON Schema, represented as a string.