mirror of https://github.com/databricks/cli.git
fix: Move templates to separate files
This commit is contained in:
Ilya Kuznetsov
parent
1b73105457
commit
e5497f75b8
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
<!-- DO NOT EDIT. This file is autogenerated with https://github.com/databricks/cli -->
|
||||
---
|
||||
description: Configuration reference for databricks.yml
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
- ✓
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
@ -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)
|
||||
Loading…
Reference in New Issue