feat: Support for resources

Makefile

@@ -36,7 +36,7 @@ schema:
 
 docs:
 	@echo "✓ Generating docs using ./bundle/internal/schema/annotations.yml file..."
-	@go run ./bundle/internal/docs ./bundle/internal/schema ./bundle/internal/docs/docs.md
+	@go run ./bundle/internal/docs ./bundle/internal/schema ./bundle/internal/docs
 	@echo "✓ Writing docs to ./bundle/internal/docs/docs.md"
 
 INTEGRATION = gotestsum --format github-actions --rerun-fails --jsonfile output.json --packages "./integration/..." -- -parallel 4 -timeout=2h

bundle/internal/docs/.gitignore

@@ -0,0 +1 @@
+output/**/*

bundle/internal/docs/README.md

@@ -3,5 +3,69 @@
 1. Install [Golang](https://go.dev/doc/install)
 2. Run `go mod download` from the repo root
 3. Run `make docs` from the repo
-4. See generated document in `./bundle/internal/docs/docs.md`
-5. To change descriptions update content in `./bundle/internal/schema/annotations.yml` and re-run `make docs`
+4. See generated documents in `./bundle/internal/docs/output` directory
+5. To change descriptions update content in `./bundle/internal/schema/annotations.yml` or `./bundle/internal/schema/annotations_openapi_overrides.yml` and re-run `make docs`
+
+For simpler usage run it together with copy command to move resulting files to local `docs` repo. Note that it will overwrite any local changes in affected files. Example:
+
+```
+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
+
+### Annotation file structure
+
+```yaml
+"<root-type-name>":
+  "<property-name>":
+    description: Description of the property, only plain text is supported
+    markdown_description: Description with markdown support, if defined it will override the value in docs and in JSON-schema
+    markdown_examples: Custom block for any example, in free form, Markdown is supported
+    title: JSON-schema title, not used in docs
+    default: Default value of the property, not used in docs
+    enum: Possible values of enum-type, not used in docs
+```
+
+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
+
+### Example annotation
+
+```yaml
+github.com/databricks/cli/bundle/config.Bundle:
+  "cluster_id":
+    "description": |-
+      The ID of a cluster to use to run the bundle.
+    "markdown_description": |-
+      The ID of a cluster to use to run the bundle. See [_](/dev-tools/bundles/settings.md#cluster_id).
+  "compute_id":
+    "description": |-
+      PLACEHOLDER
+  "databricks_cli_version":
+    "description": |-
+      The Databricks CLI version to use for the bundle.
+    "markdown_description": |-
+      The Databricks CLI version to use for the bundle. See [_](/dev-tools/bundles/settings.md#databricks_cli_version).
+  "deployment":
+    "description": |-
+      The definition of the bundle deployment
+    "markdown_description": |-
+      The definition of the bundle deployment. For supported attributes, see [_](#deployment) and [_](/dev-tools/bundles/deployment-modes.md).
+  "git":
+    "description": |-
+      The Git version control details that are associated with your bundle.
+    "markdown_description": |-
+      The Git version control details that are associated with your bundle. For supported attributes, see [_](#git) and [_](/dev-tools/bundles/settings.md#git).
+  "name":
+    "description": |-
+      The name of the bundle.
+  "uuid":
+    "description": |-
+      PLACEHOLDER
+```
+
+### TODO
+
+Add file watcher to track changes in the annotation files and re-run `make docs` script automtically

bundle/internal/docs/docs.go

@@ -81,16 +81,7 @@ 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 {
+func buildMarkdown(nodes []rootNode, outputFile, header string) error {
 	f, err := os.Create(outputFile)
 	if err != nil {
 		log.Fatal(err)
@@ -136,7 +127,7 @@ func buildMarkdown(nodes []rootNode, outputFile string) error {
 
 		if node.Example != "" {
 			m = m.LF()
-			m = m.H3("Example")
+			m = m.PlainText("**Example**")
 			m = m.LF()
 			m = m.PlainText(node.Example)
 		}

bundle/internal/docs/main.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"log"
 	"os"
-	"path/filepath"
+	"path"
 	"reflect"
 	"strings"
 
@@ -13,25 +13,68 @@ import (
 	"github.com/databricks/cli/libs/jsonschema"
 )
 
+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).
+`
+)
+
+const (
+	resourcesFileName = "resources-reference.md"
+	resourcesHeader   = `---
+description: Resources references for databricks.yml
+---
+
+# Resources reference
+
+This article provides reference for keys supported by <DABS> configuration (YAML). See [\_](/dev-tools/bundles/index.md).
+`
+)
+
 func main() {
 	if len(os.Args) != 3 {
 		fmt.Println("Usage: go run main.go <annotation-file> <output-file>")
 		os.Exit(1)
 	}
 
-	annotationFile := os.Args[1]
-	outputFile := os.Args[2]
+	annotationDir := os.Args[1]
+	docsDir := os.Args[2]
+	outputDir := path.Join(docsDir, "output")
 
-	err := generateDocs(annotationFile, outputFile)
+	if _, err := os.Stat(outputDir); os.IsNotExist(err) {
+		if err := os.MkdirAll(outputDir, 0o755); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	err := generateDocs(
+		[]string{path.Join(annotationDir, "annotations.yml")},
+		path.Join(outputDir, rootFileName),
+		reflect.TypeOf(config.Root{}),
+		rootHeader,
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	err = generateDocs(
+		[]string{path.Join(annotationDir, "annotations_openapi.yml"), path.Join(annotationDir, "annotations_openapi_overrides.yml")},
+		path.Join(outputDir, resourcesFileName),
+		reflect.TypeOf(config.Resources{}),
+		resourcesHeader,
+	)
 	if err != nil {
 		log.Fatal(err)
 	}
 }
 
-func generateDocs(workdir, outputPath string) error {
-	annotationsPath := filepath.Join(workdir, "annotations.yml")
-
-	annotations, err := annotation.LoadAndMerge([]string{annotationsPath})
+func generateDocs(inputPaths []string, outputPath string, rootType reflect.Type, header string) error {
+	annotations, err := annotation.LoadAndMerge(inputPaths)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -39,7 +82,7 @@ func generateDocs(workdir, outputPath string) error {
 	schemas := map[string]jsonschema.Schema{}
 	customFields := map[string]bool{}
 
-	s, err := jsonschema.FromType(reflect.TypeOf(config.Root{}), []func(reflect.Type, jsonschema.Schema) jsonschema.Schema{
+	s, err := jsonschema.FromType(rootType, []func(reflect.Type, jsonschema.Schema) jsonschema.Schema{
 		func(typ reflect.Type, s jsonschema.Schema) jsonschema.Schema {
 			_, isCustomField := annotations[jsonschema.TypePath(typ)]
 			if isCustomField {
@@ -75,7 +118,7 @@ func generateDocs(workdir, outputPath string) error {
 	}
 
 	nodes := getNodes(s, schemas, customFields)
-	err = buildMarkdown(nodes, outputPath)
+	err = buildMarkdown(nodes, outputPath, header)
 	if err != nil {
 		log.Fatal(err)
 	}