diff --git a/bundle/internal/docs/README.md b/bundle/internal/docs/README.md index bd61e3ee8..79f9714cf 100644 --- a/bundle/internal/docs/README.md +++ b/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 diff --git a/bundle/internal/docs/main.go b/bundle/internal/docs/main.go index e4e603b1d..0f00565c6 100644 --- a/bundle/internal/docs/main.go +++ b/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 ") @@ -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) diff --git a/bundle/internal/docs/markdown.go b/bundle/internal/docs/markdown.go index acc098aaf..612beb902 100644 --- a/bundle/internal/docs/markdown.go +++ b/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 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. ---- - -# resources - - allows you to specify information about the 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). - -## 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) () - - ✓ - - [Registered model object](/api/workspace/registeredmodels/create) - - * - [schema](#schema) () - - ✓ - - [Schema object](/api/workspace/schemas/create) - - * - [volume](#volume) () - - ✓ - - [Volume object](/api/workspace/volumes/create) -` -) - func buildMarkdown(nodes []rootNode, outputFile, header string) error { f, err := os.Create(outputFile) if err != nil { diff --git a/bundle/internal/docs/output/reference.md b/bundle/internal/docs/output/reference.md index 9a3b31359..5fa76224c 100644 --- a/bundle/internal/docs/output/reference.md +++ b/bundle/internal/docs/output/reference.md @@ -1,3 +1,4 @@ + --- description: Configuration reference for databricks.yml --- diff --git a/bundle/internal/docs/output/resources.md b/bundle/internal/docs/output/resources.md index 7ebf29b43..80ca302cf 100644 --- a/bundle/internal/docs/output/resources.md +++ b/bundle/internal/docs/output/resources.md @@ -1,3 +1,4 @@ + --- 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) - ✓ diff --git a/bundle/internal/docs/templates/reference.md b/bundle/internal/docs/templates/reference.md new file mode 100644 index 000000000..a17d53315 --- /dev/null +++ b/bundle/internal/docs/templates/reference.md @@ -0,0 +1,10 @@ + +--- +description: Configuration reference for databricks.yml +--- + +# Configuration reference + +This article provides reference for keys supported by 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). diff --git a/bundle/internal/docs/templates/resources.md b/bundle/internal/docs/templates/resources.md new file mode 100644 index 000000000..fccfac47d --- /dev/null +++ b/bundle/internal/docs/templates/resources.md @@ -0,0 +1,70 @@ + +--- +description: Learn about resources supported by Databricks Asset Bundles and how to configure them. +--- + +# resources + + allows you to specify information about the 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). + +## 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) () + - ✓ + - [Registered model object](/api/workspace/registeredmodels/create) + + * - [schema](#schema) () + - ✓ + - [Schema object](/api/workspace/schemas/create) + + * - [volume](#volume) () + - ✓ + - [Volume object](/api/workspace/volumes/create)