steve/databricks-cli
steve
/
databricks-cli
mirror of https://github.com/databricks/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
databricks-cli/bundle/schema
History
shreyas-goenka 18a216bf97
Add openapi descriptions to bundle resources (#229) 
This PR:
1. Adds autogeneration of descriptions for `resources` field
2. Autogenerates empty descriptions for any properties in DABs
3. Defines SOPs for how to refresh these descriptions
4. Adds command to generate this documentation
5. Adds Automatically copy any descriptions over to `environments`
property

Basically it provides a framework for adding descriptions to the
generated JSON schema

Tested manually and using unit tests
 		2023-03-15 03:18:51 +01:00
..
docs Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
README.md Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
docs.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
docs_test.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
openapi.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
openapi_test.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
schema.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
schema_test.go Add openapi descriptions to bundle resources (#229) 2023-03-15 03:18:51 +01:00
tracker.go JSON Schema generator for golang types (#167) 2023-01-20 16:55:44 +01:00

README.md

Overview

docs/bundle_descriptions.json contains both autogenerated as well as manually written descriptions for the json schema. Specifically

  1. resources : almost all descriptions are autogenerated from the OpenAPI spec
  2. environments : almost all descriptions are copied over from root level entities (eg: bundle, artifacts)
  3. bundle : manually editted
  4. include : manually editted
  5. workspace : manually editted
  6. artifacts : manually editted

These descriptions are rendered in the inline documentation in an IDE

SOP: Add schema descriptions for new fields in bundle config

  1. You can autogenerate empty descriptions for the new fields by running bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json
  2. Manually edit bundle_descriptions.json to add your descriptions
  3. Again run bricks bundle schema --only-docs > ~/bricks/bundle/schema/docs/bundle_descriptions.json to copy over any applicable descriptions to environments
  4. push to repo

SOP: Update descriptions in resources from a newer openapi spec

  1. Run bricks bundle schema --only-docs --openapi PATH_TO_SPEC > ~/bricks/bundle/schema/docs/bundle_descriptions.json
  2. push to repo