fix: Move templates to separate files

bundle/internal/docs/README.md

@@ -11,7 +11,7 @@ For simpler usage run it together with copy command to move resulting files to l
 make docs && cp bundle/internal/docs/output/*.md ../docs/source/dev-tools/bundles
 ```
 
-To change file names or file headers update them in `main.go` file in this directory
+To change intro sections for files update them in `templates/` directory
 
 ### Annotation file structure
 
@@ -30,6 +30,14 @@ Descriptions with `PLACEHOLDER` value are not displayed in docs and JSON-schema
 
 All relative links like `[_](/dev-tools/bundles/settings.md#cluster_id)` are kept as is in docs but converted to absolute links in JSON schema
 
+To change description for type itself (not its fields) use `"_"`:
+```yaml
+github.com/databricks/cli/bundle/config/resources.Cluster:
+  "_":
+    "markdown_description": |-
+      The cluster resource defines an [all-purpose cluster](/api/workspace/clusters/create).
+```
+
 ### Example annotation
 
 ```yaml

bundle/internal/docs/main.go

@@ -13,6 +13,11 @@ import (
 	"github.com/databricks/cli/libs/jsonschema"
 )
 
+const (
+	rootFileName      = "reference.md"
+	resourcesFileName = "resources.md"
+)
+
 func main() {
 	if len(os.Args) != 3 {
 		fmt.Println("Usage: go run main.go <annotation-file> <output-file>")
@@ -22,6 +27,7 @@ func main() {
 	annotationDir := os.Args[1]
 	docsDir := os.Args[2]
 	outputDir := path.Join(docsDir, "output")
+	templatesDir := path.Join(docsDir, "templates")
 
 	if _, err := os.Stat(outputDir); os.IsNotExist(err) {
 		if err := os.MkdirAll(outputDir, 0o755); err != nil {
@@ -29,20 +35,28 @@ func main() {
 		}
 	}
 
-	err := generateDocs(
+	rootHeader, err := os.ReadFile(path.Join(templatesDir, rootFileName))
+	if err != nil {
+		log.Fatal(err)
+	}
+	err = generateDocs(
 		[]string{path.Join(annotationDir, "annotations.yml")},
 		path.Join(outputDir, rootFileName),
 		reflect.TypeOf(config.Root{}),
-		rootHeader,
+		string(rootHeader),
 	)
 	if err != nil {
 		log.Fatal(err)
 	}
+	resourcesHeader, err := os.ReadFile(path.Join(templatesDir, resourcesFileName))
+	if err != nil {
+		log.Fatal(err)
+	}
 	err = generateDocs(
 		[]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{}),
-		resourcesHeader,
+		string(resourcesHeader),
 	)
 	if err != nil {
 		log.Fatal(err)

bundle/internal/docs/markdown.go

@@ -9,94 +9,6 @@ import (
 	md "github.com/nao1215/markdown"
 )
 
-const (
-	rootFileName = "reference.md"
-	rootHeader   = `---
-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).
-
-For complete bundle examples, see [_](/dev-tools/bundles/resource-examples.md) and the [bundle-examples GitHub repository](https://github.com/databricks/bundle-examples).
-`
-)
-
-const (
-	resourcesFileName = "resources.md"
-	resourcesHeader   = `---
-description: Learn about resources supported by Databricks Asset Bundles and how to configure them.
----
-
-# <DABS> resources
-
-<DABS> allows you to specify information about the <Databricks> resources used by the bundle in the ` + "`" + `resources` + "`" + ` mapping in the bundle configuration. See [resources mapping](/dev-tools/bundles/settings.md#resources) and [resources key reference](/dev-tools/bundles/reference.md#resources).
-
-This article outlines supported resource types for bundles and provides details and an example for each supported type. For additional examples, see [_](/dev-tools/bundles/resource-examples.md).
-
-## <a id="resource-types"></a> Supported resources
-
-The following table lists supported resource types for bundles. Some resources can be created by defining them in a bundle and deploying the bundle, and some resources only support referencing an existing resource to include in the bundle.
-
-Resources are defined using the corresponding [Databricks REST API](/api/workspace/introduction) object's create operation request payload, where the object's supported fields, expressed as YAML, are the resource's supported properties. Links to documentation for each resource's corresponding payloads are listed in the table.
-
-.. tip:: The ` + "`" + `databricks bundle validate` + "`" + ` command returns warnings if unknown resource properties are found in bundle configuration files.
-
-
-.. list-table::
-    :header-rows: 1
-
-    * - Resource
-      - Create support
-      - Corresponding REST API object
-
-    * - [cluster](#cluster)
-      - ✓
-      - [Cluster object](/api/workspace/clusters/create)
-
-    * - [dashboard](#dashboard)
-      -
-      - [Dashboard object](/api/workspace/lakeview/create)
-
-    * - [experiment](#experiment)
-      - ✓
-      - [Experiment object](/api/workspace/experiments/createexperiment)
-
-    * - [job](#job)
-      - ✓
-      - [Job object](/api/workspace/jobs/create)
-
-    * - [model (legacy)](#model-legacy)
-      - ✓
-      - [Model (legacy) object](/api/workspace/modelregistry/createmodel)
-
-    * - [model_serving_endpoint](#model-serving-endpoint)
-      - ✓
-      - [Model serving endpoint object](/api/workspace/servingendpoints/create)
-
-    * - [pipeline](#pipeline)
-      - ✓
-      - [Pipeline object]](/api/workspace/pipelines/create)
-
-    * - [quality_monitor](#quality-monitor)
-      - ✓
-      - [Quality monitor object](/api/workspace/qualitymonitors/create)
-
-    * - [registered_model](#registered-model) (<UC>)
-      - ✓
-      - [Registered model object](/api/workspace/registeredmodels/create)
-
-    * - [schema](#schema) (<UC>)
-      - ✓
-      - [Schema object](/api/workspace/schemas/create)
-
-    * - [volume](#volume) (<UC>)
-      - ✓
-      - [Volume object](/api/workspace/volumes/create)
-`
-)
-
 func buildMarkdown(nodes []rootNode, outputFile, header string) error {
 	f, err := os.Create(outputFile)
 	if err != nil {

bundle/internal/docs/output/reference.md

@@ -1,3 +1,4 @@
+<!-- DO NOT EDIT. This file is autogenerated with https://github.com/databricks/cli -->
 ---
 description: Configuration reference for databricks.yml
 ---

bundle/internal/docs/output/resources.md

@@ -1,3 +1,4 @@
+<!-- DO NOT EDIT. This file is autogenerated with https://github.com/databricks/cli -->
 ---
 description: Learn about resources supported by Databricks Asset Bundles and how to configure them.
 ---
@@ -50,7 +51,7 @@ Resources are defined using the corresponding [Databricks REST API](/api/workspa
 
     * - [pipeline](#pipeline)
       - ✓
-      - [Pipeline object]](/api/workspace/pipelines/create)
+      - [Pipeline object](/api/workspace/pipelines/create)
 
     * - [quality_monitor](#quality-monitor)
       - ✓

bundle/internal/docs/templates/reference.md

@@ -0,0 +1,10 @@
+<!-- DO NOT EDIT. This file is autogenerated with https://github.com/databricks/cli -->
+---
+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).
+
+For complete bundle examples, see [_](/dev-tools/bundles/resource-examples.md) and the [bundle-examples GitHub repository](https://github.com/databricks/bundle-examples).

bundle/internal/docs/templates/resources.md

@@ -0,0 +1,70 @@
+<!-- DO NOT EDIT. This file is autogenerated with https://github.com/databricks/cli -->
+---
+description: Learn about resources supported by Databricks Asset Bundles and how to configure them.
+---
+
+# <DABS> resources
+
+<DABS> allows you to specify information about the <Databricks> resources used by the bundle in the `resources` mapping in the bundle configuration. See [resources mapping](/dev-tools/bundles/settings.md#resources) and [resources key reference](/dev-tools/bundles/reference.md#resources).
+
+This article outlines supported resource types for bundles and provides details and an example for each supported type. For additional examples, see [_](/dev-tools/bundles/resource-examples.md).
+
+## <a id="resource-types"></a> Supported resources
+
+The following table lists supported resource types for bundles. Some resources can be created by defining them in a bundle and deploying the bundle, and some resources only support referencing an existing resource to include in the bundle.
+
+Resources are defined using the corresponding [Databricks REST API](/api/workspace/introduction) object's create operation request payload, where the object's supported fields, expressed as YAML, are the resource's supported properties. Links to documentation for each resource's corresponding payloads are listed in the table.
+
+.. tip:: The `databricks bundle validate` command returns warnings if unknown resource properties are found in bundle configuration files.
+
+
+.. list-table::
+    :header-rows: 1
+
+    * - Resource
+      - Create support
+      - Corresponding REST API object
+
+    * - [cluster](#cluster)
+      - ✓
+      - [Cluster object](/api/workspace/clusters/create)
+
+    * - [dashboard](#dashboard)
+      -
+      - [Dashboard object](/api/workspace/lakeview/create)
+
+    * - [experiment](#experiment)
+      - ✓
+      - [Experiment object](/api/workspace/experiments/createexperiment)
+
+    * - [job](#job)
+      - ✓
+      - [Job object](/api/workspace/jobs/create)
+
+    * - [model (legacy)](#model-legacy)
+      - ✓
+      - [Model (legacy) object](/api/workspace/modelregistry/createmodel)
+
+    * - [model_serving_endpoint](#model-serving-endpoint)
+      - ✓
+      - [Model serving endpoint object](/api/workspace/servingendpoints/create)
+
+    * - [pipeline](#pipeline)
+      - ✓
+      - [Pipeline object](/api/workspace/pipelines/create)
+
+    * - [quality_monitor](#quality-monitor)
+      - ✓
+      - [Quality monitor object](/api/workspace/qualitymonitors/create)
+
+    * - [registered_model](#registered-model) (<UC>)
+      - ✓
+      - [Registered model object](/api/workspace/registeredmodels/create)
+
+    * - [schema](#schema) (<UC>)
+      - ✓
+      - [Schema object](/api/workspace/schemas/create)
+
+    * - [volume](#volume) (<UC>)
+      - ✓
+      - [Volume object](/api/workspace/volumes/create)