diff --git a/Makefile b/Makefile index 2db0ba0bd..b309e2908 100644 --- a/Makefile +++ b/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 diff --git a/bundle/internal/docs/.gitignore b/bundle/internal/docs/.gitignore new file mode 100644 index 000000000..294bc037f --- /dev/null +++ b/bundle/internal/docs/.gitignore @@ -0,0 +1 @@ +output/**/* diff --git a/bundle/internal/docs/README.md b/bundle/internal/docs/README.md index 77d9abcad..0dd5727f4 100644 --- a/bundle/internal/docs/README.md +++ b/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 +"": + "": + 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 diff --git a/bundle/internal/docs/docs.go b/bundle/internal/docs/docs.go index 57d42ce14..dd9377487 100644 --- a/bundle/internal/docs/docs.go +++ b/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 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) } diff --git a/bundle/internal/docs/docs.md b/bundle/internal/docs/docs.md deleted file mode 100644 index 04b1e83d3..000000000 --- a/bundle/internal/docs/docs.md +++ /dev/null @@ -1,1019 +0,0 @@ ---- -description: Configuration reference for databricks.yml ---- - -# Configuration reference - -This article provides reference for keys supported by configuration (YAML). See [\_](/dev-tools/bundles/index.md). - - -## artifacts - -Defines the attributes to build an artifact - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - - - Map - - Item of the `artifacts` map - -Each item has the following attributes: - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - build - - String - - An optional set of non-default build commands that you want to run locally before deployment. For Python wheel builds, the Databricks CLI assumes that it can find a local install of the Python wheel package to run builds, and it runs the command python setup.py bdist_wheel by default during each bundle deployment. To specify multiple build commands, separate each command with double-ampersand (&&) characters. - - * - executable - - String - - The executable type. - - * - files - - Sequence - - The source files for the artifact, defined as an [_](#artifact_file). - - * - path - - String - - The location where the built artifact will be saved. - - * - type - - String - - The type of the artifact. Valid values are `wheel` or `jar` - - -### Example - -```yaml -artifacts: - default: - type: whl - build: poetry build - path: . -``` - -## bundle - -The attributes of the bundle. See [_](/dev-tools/bundles/settings.md#bundle) - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - cluster_id - - String - - The ID of a cluster to use to run the bundle. See [_](/dev-tools/bundles/settings.md#cluster_id). - - * - compute_id - - String - - - - * - databricks_cli_version - - String - - The Databricks CLI version to use for the bundle. See [_](/dev-tools/bundles/settings.md#databricks_cli_version). - - * - deployment - - Map - - The definition of the bundle deployment. For supported attributes, see [_](#deployment) and [_](/dev-tools/bundles/deployment-modes.md). - - * - git - - Map - - The Git version control details that are associated with your bundle. For supported attributes, see [_](#git) and [_](/dev-tools/bundles/settings.md#git). - - * - name - - String - - The name of the bundle. - - * - uuid - - String - - - - -### bundle.deployment - -The definition of the bundle deployment - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - fail_on_active_runs - - Boolean - - Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted. - - * - lock - - Map - - The deployment lock attributes. See [_](#lock). - - -### bundle.deployment.lock - -The deployment lock attributes. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - enabled - - Boolean - - Whether this lock is enabled. - - * - force - - Boolean - - Whether to force this lock if it is enabled. - - -### bundle.git - -The Git version control details that are associated with your bundle. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - branch - - String - - The Git branch name. See [_](/dev-tools/bundles/settings.md#git). - - * - origin_url - - String - - The origin URL of the repository. See [_](/dev-tools/bundles/settings.md#git). - - -## experimental - -Defines attributes for experimental features. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - pydabs - - Map - - The PyDABs configuration. - - * - python_wheel_wrapper - - Boolean - - Whether to use a Python wheel wrapper - - * - scripts - - Map - - The commands to run - - * - use_legacy_run_as - - Boolean - - Whether to use the legacy run_as behavior - - -### experimental.pydabs - -The PyDABs configuration. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - enabled - - Boolean - - Whether or not PyDABs (Private Preview) is enabled - - * - import - - Sequence - - The PyDABs project to import to discover resources, resource generator and mutators - - * - venv_path - - String - - The Python virtual environment path - - -## include - -Specifies a list of path globs that contain configuration files to include within the bundle. See [_](/dev-tools/bundles/settings.md#include) - - -## permissions - -**`Type: Array`** - -Defines the permissions to apply to experiments, jobs, pipelines, and models defined in the bundle. See [_](/dev-tools/bundles/settings.md#permissions) and [_](/dev-tools/bundles/permissions.md). - -Each item of `permissions` has the following attributes: - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - group_name - - String - - The name of the group that has the permission set in level. - - * - level - - String - - The allowed permission for user, group, service principal defined for this permission. - - * - service_principal_name - - String - - The name of the service principal that has the permission set in level. - - * - user_name - - String - - The name of the user that has the permission set in level. - - -### Example - -```yaml -permissions: - - level: CAN_VIEW - group_name: test-group - - level: CAN_MANAGE - user_name: someone@example.com - - level: CAN_RUN - service_principal_name: 123456-abcdef -``` - -## presets - -Defines bundle deployment presets. See [_](/dev-tools/bundles/deployment-modes.md#presets). - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - jobs_max_concurrent_runs - - Integer - - The maximum concurrent runs for a job. - - * - name_prefix - - String - - The prefix for job runs of the bundle. - - * - pipelines_development - - Boolean - - Whether pipeline deployments should be locked in development mode. - - * - source_linked_deployment - - Boolean - - Whether to link the deployment to the bundle source. - - * - tags - - Map - - The tags for the bundle deployment. - - * - trigger_pause_status - - String - - A pause status to apply to all job triggers and schedules. Valid values are PAUSED or UNPAUSED. - - -## resources - -Specifies information about the Databricks resources used by the bundle. See [_](/dev-tools/bundles/resources.md). - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - clusters - - Map - - The cluster definitions for the bundle. See [_](/dev-tools/bundles/resources.md#cluster) - - * - dashboards - - Map - - The dashboard definitions for the bundle. See [_](/dev-tools/bundles/resources.md#dashboard) - - * - experiments - - Map - - The experiment definitions for the bundle. See [_](/dev-tools/bundles/resources.md#experiment) - - * - jobs - - Map - - The job definitions for the bundle. See [_](/dev-tools/bundles/resources.md#job) - - * - model_serving_endpoints - - Map - - The model serving endpoint definitions for the bundle. See [_](/dev-tools/bundles/resources.md#model_serving_endpoint) - - * - models - - Map - - The model definitions for the bundle. See [_](/dev-tools/bundles/resources.md#model) - - * - pipelines - - Map - - The pipeline definitions for the bundle. See [_](/dev-tools/bundles/resources.md#pipeline) - - * - quality_monitors - - Map - - The quality monitor definitions for the bundle. See [_](/dev-tools/bundles/resources.md#quality_monitor) - - * - registered_models - - Map - - The registered model definitions for the bundle. See [_](/dev-tools/bundles/resources.md#registered_model) - - * - schemas - - Map - - The schema definitions for the bundle. See [_](/dev-tools/bundles/resources.md#schema) - - * - volumes - - Map - - - - -## run_as - -The identity to use to run the bundle. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - service_principal_name - - String - - - - * - user_name - - String - - - - -## sync - -The files and file paths to include or exclude in the bundle. See [_](/dev-tools/bundles/) - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - exclude - - Sequence - - A list of files or folders to exclude from the bundle. - - * - include - - Sequence - - A list of files or folders to include in the bundle. - - * - paths - - Sequence - - The local folder paths, which can be outside the bundle root, to synchronize to the workspace when the bundle is deployed. - - -## targets - -Defines deployment targets for the bundle. - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - - - Map - - Item of the `targets` map - -Each item has the following attributes: - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - artifacts - - Map - - The artifacts to include in the target deployment. See [_](#artifact) - - * - bundle - - Map - - The name of the bundle when deploying to this target. - - * - cluster_id - - String - - The ID of the cluster to use for this target. - - * - compute_id - - String - - Deprecated. The ID of the compute to use for this target. - - * - default - - Boolean - - Whether this target is the default target. - - * - git - - Map - - The Git version control settings for the target. See [_](#git). - - * - mode - - String - - The deployment mode for the target. Valid values are `development` or `production`. See [_](/dev-tools/bundles/deployment-modes.md). - - * - permissions - - Sequence - - The permissions for deploying and running the bundle in the target. See [_](#permission). - - * - presets - - Map - - The deployment presets for the target. See [_](#preset). - - * - resources - - Map - - The resource definitions for the target. See [_](#resources). - - * - run_as - - Map - - The identity to use to run the bundle. See [_](#job_run_as) and [_](/dev-tools/bundles/run_as.md). - - * - sync - - Map - - The local paths to sync to the target workspace when a bundle is run or deployed. See [_](#sync). - - * - variables - - Map - - The custom variable definitions for the target. See [_](/dev-tools/bundles/settings.md#variables) and [_](/dev-tools/bundles/variables.md). - - * - workspace - - Map - - The Databricks workspace for the target. [_](#workspace) - - -### targets.bundle - -The name of the bundle when deploying to this target. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - cluster_id - - String - - The ID of a cluster to use to run the bundle. See [_](/dev-tools/bundles/settings.md#cluster_id). - - * - compute_id - - String - - - - * - databricks_cli_version - - String - - The Databricks CLI version to use for the bundle. See [_](/dev-tools/bundles/settings.md#databricks_cli_version). - - * - deployment - - Map - - The definition of the bundle deployment. For supported attributes, see [_](#deployment) and [_](/dev-tools/bundles/deployment-modes.md). - - * - git - - Map - - The Git version control details that are associated with your bundle. For supported attributes, see [_](#git) and [_](/dev-tools/bundles/settings.md#git). - - * - name - - String - - The name of the bundle. - - * - uuid - - String - - - - -### targets.bundle.deployment - -The definition of the bundle deployment - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - fail_on_active_runs - - Boolean - - Whether to fail on active runs. If this is set to true a deployment that is running can be interrupted. - - * - lock - - Map - - The deployment lock attributes. See [_](#lock). - - -### targets.bundle.deployment.lock - -The deployment lock attributes. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - enabled - - Boolean - - Whether this lock is enabled. - - * - force - - Boolean - - Whether to force this lock if it is enabled. - - -### targets.bundle.git - -The Git version control details that are associated with your bundle. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - branch - - String - - The Git branch name. See [_](/dev-tools/bundles/settings.md#git). - - * - origin_url - - String - - The origin URL of the repository. See [_](/dev-tools/bundles/settings.md#git). - - -### targets.git - -The Git version control settings for the target. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - branch - - String - - The Git branch name. See [_](/dev-tools/bundles/settings.md#git). - - * - origin_url - - String - - The origin URL of the repository. See [_](/dev-tools/bundles/settings.md#git). - - -### targets.presets - -The deployment presets for the target. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - jobs_max_concurrent_runs - - Integer - - The maximum concurrent runs for a job. - - * - name_prefix - - String - - The prefix for job runs of the bundle. - - * - pipelines_development - - Boolean - - Whether pipeline deployments should be locked in development mode. - - * - source_linked_deployment - - Boolean - - Whether to link the deployment to the bundle source. - - * - tags - - Map - - The tags for the bundle deployment. - - * - trigger_pause_status - - String - - A pause status to apply to all job triggers and schedules. Valid values are PAUSED or UNPAUSED. - - -### targets.resources - -The resource definitions for the target. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - clusters - - Map - - The cluster definitions for the bundle. See [_](/dev-tools/bundles/resources.md#cluster) - - * - dashboards - - Map - - The dashboard definitions for the bundle. See [_](/dev-tools/bundles/resources.md#dashboard) - - * - experiments - - Map - - The experiment definitions for the bundle. See [_](/dev-tools/bundles/resources.md#experiment) - - * - jobs - - Map - - The job definitions for the bundle. See [_](/dev-tools/bundles/resources.md#job) - - * - model_serving_endpoints - - Map - - The model serving endpoint definitions for the bundle. See [_](/dev-tools/bundles/resources.md#model_serving_endpoint) - - * - models - - Map - - The model definitions for the bundle. See [_](/dev-tools/bundles/resources.md#model) - - * - pipelines - - Map - - The pipeline definitions for the bundle. See [_](/dev-tools/bundles/resources.md#pipeline) - - * - quality_monitors - - Map - - The quality monitor definitions for the bundle. See [_](/dev-tools/bundles/resources.md#quality_monitor) - - * - registered_models - - Map - - The registered model definitions for the bundle. See [_](/dev-tools/bundles/resources.md#registered_model) - - * - schemas - - Map - - The schema definitions for the bundle. See [_](/dev-tools/bundles/resources.md#schema) - - * - volumes - - Map - - - - -### targets.sync - -The local paths to sync to the target workspace when a bundle is run or deployed. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - exclude - - Sequence - - A list of files or folders to exclude from the bundle. - - * - include - - Sequence - - A list of files or folders to include in the bundle. - - * - paths - - Sequence - - The local folder paths, which can be outside the bundle root, to synchronize to the workspace when the bundle is deployed. - - -### targets.workspace - -The Databricks workspace for the target. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - artifact_path - - String - - The artifact path to use within the workspace for both deployments and workflow runs - - * - auth_type - - String - - The authentication type. - - * - azure_client_id - - String - - The Azure client ID - - * - azure_environment - - String - - The Azure environment - - * - azure_login_app_id - - String - - The Azure login app ID - - * - azure_tenant_id - - String - - The Azure tenant ID - - * - azure_use_msi - - Boolean - - Whether to use MSI for Azure - - * - azure_workspace_resource_id - - String - - The Azure workspace resource ID - - * - client_id - - String - - The client ID for the workspace - - * - file_path - - String - - The file path to use within the workspace for both deployments and workflow runs - - * - google_service_account - - String - - The Google service account name - - * - host - - String - - The Databricks workspace host URL - - * - profile - - String - - The Databricks workspace profile name - - * - resource_path - - String - - The workspace resource path - - * - root_path - - String - - The Databricks workspace root path - - * - state_path - - String - - The workspace state path - - -## variables - -A Map that defines the custom variables for the bundle, where each key is the name of the variable, and the value is a Map that defines the variable. - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - - - Map - - Item of the `variables` map - -Each item has the following attributes: - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - default - - Any - - - - * - description - - String - - The description of the variable - - * - lookup - - Map - - The name of the `alert`, `cluster_policy`, `cluster`, `dashboard`, `instance_pool`, `job`, `metastore`, `pipeline`, `query`, `service_principal`, or `warehouse` object for which to retrieve an ID." - - * - type - - String - - The type of the variable. - - -### variables.lookup - -The name of the alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principal, or warehouse object for which to retrieve an ID. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - alert - - String - - - - * - cluster - - String - - - - * - cluster_policy - - String - - - - * - dashboard - - String - - - - * - instance_pool - - String - - - - * - job - - String - - - - * - metastore - - String - - - - * - notification_destination - - String - - - - * - pipeline - - String - - - - * - query - - String - - - - * - service_principal - - String - - - - * - warehouse - - String - - - - -## workspace - -Defines the Databricks workspace for the bundle. - - - -.. list-table:: - :header-rows: 1 - - * - Key - - Type - - Description - - * - artifact_path - - String - - The artifact path to use within the workspace for both deployments and workflow runs - - * - auth_type - - String - - The authentication type. - - * - azure_client_id - - String - - The Azure client ID - - * - azure_environment - - String - - The Azure environment - - * - azure_login_app_id - - String - - The Azure login app ID - - * - azure_tenant_id - - String - - The Azure tenant ID - - * - azure_use_msi - - Boolean - - Whether to use MSI for Azure - - * - azure_workspace_resource_id - - String - - The Azure workspace resource ID - - * - client_id - - String - - The client ID for the workspace - - * - file_path - - String - - The file path to use within the workspace for both deployments and workflow runs - - * - google_service_account - - String - - The Google service account name - - * - host - - String - - The Databricks workspace host URL - - * - profile - - String - - The Databricks workspace profile name - - * - resource_path - - String - - The workspace resource path - - * - root_path - - String - - The Databricks workspace root path - - * - state_path - - String - - The workspace state path - \ No newline at end of file diff --git a/bundle/internal/docs/main.go b/bundle/internal/docs/main.go index f0e8ef2e0..beb4954c8 100644 --- a/bundle/internal/docs/main.go +++ b/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 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 configuration (YAML). See [\_](/dev-tools/bundles/index.md). +` +) + func main() { if len(os.Args) != 3 { fmt.Println("Usage: go run main.go ") 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) }