address comments

databricks · Jan 26, 2024 · aef7af4 · aef7af4
1 parent 5e72c63
commit aef7af4
Show file tree

Hide file tree

Showing 119 changed files with 195 additions and 183 deletions.
diff --git a/docs/account/account-oauth2.rst b/docs/account/account-oauth2.rst
diff --git a/docs/account/billable_usage.rst → docs/account/billing/billable_usage.rst b/docs/account/billable_usage.rst → docs/account/billing/billable_usage.rst
diff --git a/docs/account/budgets.rst → docs/account/billing/budgets.rst b/docs/account/budgets.rst → docs/account/billing/budgets.rst
diff --git a/docs/account/account-billing.rst → docs/account/billing/index.rst b/docs/account/account-billing.rst → docs/account/billing/index.rst
@@ -5,8 +5,8 @@ Billing
 Configure different aspects of Databricks billing and usage.
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  billable_usage
-  budgets
-  log_delivery
+   billable_usage
+   budgets
+   log_delivery
diff --git a/docs/account/log_delivery.rst → docs/account/billing/log_delivery.rst b/docs/account/log_delivery.rst → docs/account/billing/log_delivery.rst
diff --git a/docs/account/account-catalog.rst → docs/account/catalog/index.rst b/docs/account/account-catalog.rst → docs/account/catalog/index.rst
@@ -5,8 +5,8 @@ Unity Catalog
 Configure data governance with Unity Catalog for metastores, catalogs, schemas, tables, external locations, and storage credentials
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  metastore_assignments
-  metastores
-  storage_credentials
+   metastore_assignments
+   metastores
+   storage_credentials
diff --git a/docs/account/metastore_assignments.rst → ...account/catalog/metastore_assignments.rst b/docs/account/metastore_assignments.rst → ...account/catalog/metastore_assignments.rst
diff --git a/docs/account/metastores.rst → docs/account/catalog/metastores.rst b/docs/account/metastores.rst → docs/account/catalog/metastores.rst
diff --git a/docs/account/storage_credentials.rst → docs/account/catalog/storage_credentials.rst b/docs/account/storage_credentials.rst → docs/account/catalog/storage_credentials.rst
diff --git a/docs/account/access_control.rst → docs/account/iam/access_control.rst b/docs/account/access_control.rst → docs/account/iam/access_control.rst
diff --git a/docs/account/groups.rst → docs/account/iam/groups.rst b/docs/account/groups.rst → docs/account/iam/groups.rst
diff --git a/docs/account/account-iam.rst → docs/account/iam/index.rst b/docs/account/account-iam.rst → docs/account/iam/index.rst
@@ -5,10 +5,10 @@ Identity and Access Management
 Manage users, service principals, groups and their permissions in Accounts and Workspaces
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  access_control
-  groups
-  service_principals
-  users
-  workspace_assignment
+   access_control
+   groups
+   service_principals
+   users
+   workspace_assignment
diff --git a/docs/account/service_principals.rst → docs/account/iam/service_principals.rst b/docs/account/service_principals.rst → docs/account/iam/service_principals.rst
diff --git a/docs/account/users.rst → docs/account/iam/users.rst b/docs/account/users.rst → docs/account/iam/users.rst
diff --git a/docs/account/workspace_assignment.rst → docs/account/iam/workspace_assignment.rst b/docs/account/workspace_assignment.rst → docs/account/iam/workspace_assignment.rst
diff --git a/docs/account/index.rst b/docs/account/index.rst
@@ -5,11 +5,11 @@ Account APIs
 These APIs are available from AccountClient
 
 .. toctree::
-  :maxdepth: 1
-
-  account-iam
-  account-catalog
-  account-settings
-  account-provisioning
-  account-billing
-  account-oauth2
+   :maxdepth: 1
+
+   iam/index
+   catalog/index
+   settings/index
+   provisioning/index
+   billing/index
+   oauth2/index
diff --git a/docs/account/custom_app_integration.rst → ...account/oauth2/custom_app_integration.rst b/docs/account/custom_app_integration.rst → ...account/oauth2/custom_app_integration.rst
diff --git a/docs/account/oauth2/index.rst b/docs/account/oauth2/index.rst
@@ -0,0 +1,13 @@
+
+OAuth
+=====
+
+Configure OAuth 2.0 application registrations for Databricks
+
+.. toctree::
+   :maxdepth: 1
+
+   custom_app_integration
+   o_auth_published_apps
+   published_app_integration
+   service_principal_secrets
diff --git a/docs/account/o_auth_published_apps.rst → .../account/oauth2/o_auth_published_apps.rst b/docs/account/o_auth_published_apps.rst → .../account/oauth2/o_auth_published_apps.rst
diff --git a/docs/account/published_app_integration.rst → ...ount/oauth2/published_app_integration.rst b/docs/account/published_app_integration.rst → ...ount/oauth2/published_app_integration.rst
diff --git a/docs/account/service_principal_secrets.rst → ...ount/oauth2/service_principal_secrets.rst b/docs/account/service_principal_secrets.rst → ...ount/oauth2/service_principal_secrets.rst
diff --git a/docs/account/credentials.rst → docs/account/provisioning/credentials.rst b/docs/account/credentials.rst → docs/account/provisioning/credentials.rst
diff --git a/docs/account/encryption_keys.rst → .../account/provisioning/encryption_keys.rst b/docs/account/encryption_keys.rst → .../account/provisioning/encryption_keys.rst
diff --git a/docs/account/account-provisioning.rst → docs/account/provisioning/index.rst b/docs/account/account-provisioning.rst → docs/account/provisioning/index.rst
@@ -5,12 +5,12 @@ Provisioning
 Resource management for secure Databricks Workspace deployment, cross-account IAM roles, storage, encryption, networking and private access.
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  credentials
-  encryption_keys
-  networks
-  private_access
-  storage
-  vpc_endpoints
-  workspaces
+   credentials
+   encryption_keys
+   networks
+   private_access
+   storage
+   vpc_endpoints
+   workspaces
diff --git a/docs/account/networks.rst → docs/account/provisioning/networks.rst b/docs/account/networks.rst → docs/account/provisioning/networks.rst
diff --git a/docs/account/private_access.rst → docs/account/provisioning/private_access.rst b/docs/account/private_access.rst → docs/account/provisioning/private_access.rst
diff --git a/docs/account/storage.rst → docs/account/provisioning/storage.rst b/docs/account/storage.rst → docs/account/provisioning/storage.rst
diff --git a/docs/account/vpc_endpoints.rst → docs/account/provisioning/vpc_endpoints.rst b/docs/account/vpc_endpoints.rst → docs/account/provisioning/vpc_endpoints.rst
diff --git a/docs/account/workspaces.rst → docs/account/provisioning/workspaces.rst b/docs/account/workspaces.rst → docs/account/provisioning/workspaces.rst
diff --git a/docs/account/account-settings.rst → docs/account/settings/index.rst b/docs/account/account-settings.rst → docs/account/settings/index.rst
@@ -5,8 +5,8 @@ Settings
 Manage security settings for Accounts and Workspaces
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  ip_access_lists
-  network_connectivity
-  settings
+   ip_access_lists
+   network_connectivity
+   settings
diff --git a/docs/account/ip_access_lists.rst → docs/account/settings/ip_access_lists.rst b/docs/account/ip_access_lists.rst → docs/account/settings/ip_access_lists.rst
diff --git a/docs/account/network_connectivity.rst → ...account/settings/network_connectivity.rst b/docs/account/network_connectivity.rst → ...account/settings/network_connectivity.rst
diff --git a/docs/account/settings.rst → docs/account/settings/settings.rst b/docs/account/settings.rst → docs/account/settings/settings.rst
diff --git a/docs/gen-client-docs.py b/docs/gen-client-docs.py
@@ -299,7 +299,13 @@ def service_docs(self, client_inst) -> list[ServiceDoc]:
     def _should_document(obj):
         return is_dataclass(obj) or (type(obj) == type and issubclass(obj, Enum))
 
+    @staticmethod
+    def _make_folder_if_not_exists(folder):
+        if not os.path.exists(folder):
+            os.makedirs(folder)
+
     def write_dataclass_docs(self):
+        self._make_folder_if_not_exists(f'{__dir__}/dbdataclasses')
         for pkg in self.packages:
             module = importlib.import_module(f'databricks.sdk.service.{pkg.name}')
             all_members = [name for name, _ in inspect.getmembers(module, predicate=self._should_document)]
@@ -333,8 +339,10 @@ def load_client(self, client, folder, label, description):
         service_docs = self.service_docs(client)
         for svc in service_docs:
             client_services.append(svc.service_name)
-            package_to_services[svc.tag.package.name].append(svc.service_name)
-            with open(f'{__dir__}/{folder}/{svc.service_name}.rst', 'w') as f:
+            package = svc.tag.package.name
+            package_to_services[package].append(svc.service_name)
+            self._make_folder_if_not_exists(f'{__dir__}/{folder}/{package}')
+            with open(f'{__dir__}/{folder}/{package}/{svc.service_name}.rst', 'w') as f:
                 f.write(svc.as_rst())
         ordered_packages = []
         for pkg in self.packages:
@@ -345,32 +353,36 @@ def load_client(self, client, folder, label, description):
         self._write_client_packages(folder, label, description, ordered_packages)
 
     def _write_client_packages(self, folder: str, label: str, description: str, packages: list[str]):
+        """Writes out the top-level index for the APIs supported by a client."""
+        self._make_folder_if_not_exists(f'{__dir__}/{folder}')
         with open(f'{__dir__}/{folder}/index.rst', 'w') as f:
-            all = "\n  ".join([f'{folder}-{name}' for name in packages])
+            all = "\n   ".join([f'{name}/index' for name in packages])
             f.write(f'''
 {label}
 {'=' * len(label)}
 
 {description}
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  {all}''')
+   {all}''')
 
     def _write_client_package_doc(self, folder: str, pkg: Package, services: list[str]):
-        with open(f'{__dir__}/{folder}/{folder}-{pkg.name}.rst', 'w') as f:
-            all = "\n  ".join(services)
+        """Writes out the index for a single package supported by a client."""
+        self._make_folder_if_not_exists(f'{__dir__}/{folder}/{pkg.name}')
+        with open(f'{__dir__}/{folder}/{pkg.name}/index.rst', 'w') as f:
+            all = "\n   ".join(services)
             f.write(f'''
 {pkg.label}
 {'=' * len(pkg.label)}
 
 {pkg.description}
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  {all}''')
+   {all}''')
 
 
 if __name__ == '__main__':

diff --git a/docs/images/styles.css b/docs/images/styles.css
diff --git a/docs/workspace/artifact_allowlists.rst → ...workspace/catalog/artifact_allowlists.rst b/docs/workspace/artifact_allowlists.rst → ...workspace/catalog/artifact_allowlists.rst
diff --git a/docs/workspace/catalogs.rst → docs/workspace/catalog/catalogs.rst b/docs/workspace/catalogs.rst → docs/workspace/catalog/catalogs.rst
diff --git a/docs/workspace/connections.rst → docs/workspace/catalog/connections.rst b/docs/workspace/connections.rst → docs/workspace/catalog/connections.rst
diff --git a/docs/workspace/external_locations.rst → .../workspace/catalog/external_locations.rst b/docs/workspace/external_locations.rst → .../workspace/catalog/external_locations.rst
diff --git a/docs/workspace/functions.rst → docs/workspace/catalog/functions.rst b/docs/workspace/functions.rst → docs/workspace/catalog/functions.rst
diff --git a/docs/workspace/grants.rst → docs/workspace/catalog/grants.rst b/docs/workspace/grants.rst → docs/workspace/catalog/grants.rst
diff --git a/docs/workspace/catalog/index.rst b/docs/workspace/catalog/index.rst
@@ -0,0 +1,25 @@
+
+Unity Catalog
+=============
+
+Configure data governance with Unity Catalog for metastores, catalogs, schemas, tables, external locations, and storage credentials
+
+.. toctree::
+   :maxdepth: 1
+
+   artifact_allowlists
+   catalogs
+   connections
+   external_locations
+   functions
+   grants
+   metastores
+   model_versions
+   registered_models
+   schemas
+   storage_credentials
+   system_schemas
+   table_constraints
+   tables
+   volumes
+   workspace_bindings
diff --git a/docs/workspace/metastores.rst → docs/workspace/catalog/metastores.rst b/docs/workspace/metastores.rst → docs/workspace/catalog/metastores.rst
diff --git a/docs/workspace/model_versions.rst → docs/workspace/catalog/model_versions.rst b/docs/workspace/model_versions.rst → docs/workspace/catalog/model_versions.rst
diff --git a/docs/workspace/registered_models.rst → docs/workspace/catalog/registered_models.rst b/docs/workspace/registered_models.rst → docs/workspace/catalog/registered_models.rst
diff --git a/docs/workspace/schemas.rst → docs/workspace/catalog/schemas.rst b/docs/workspace/schemas.rst → docs/workspace/catalog/schemas.rst
diff --git a/docs/workspace/storage_credentials.rst → ...workspace/catalog/storage_credentials.rst b/docs/workspace/storage_credentials.rst → ...workspace/catalog/storage_credentials.rst
diff --git a/docs/workspace/system_schemas.rst → docs/workspace/catalog/system_schemas.rst b/docs/workspace/system_schemas.rst → docs/workspace/catalog/system_schemas.rst
diff --git a/docs/workspace/table_constraints.rst → docs/workspace/catalog/table_constraints.rst b/docs/workspace/table_constraints.rst → docs/workspace/catalog/table_constraints.rst
diff --git a/docs/workspace/tables.rst → docs/workspace/catalog/tables.rst b/docs/workspace/tables.rst → docs/workspace/catalog/tables.rst
diff --git a/docs/workspace/volumes.rst → docs/workspace/catalog/volumes.rst b/docs/workspace/volumes.rst → docs/workspace/catalog/volumes.rst
diff --git a/docs/workspace/workspace_bindings.rst → .../workspace/catalog/workspace_bindings.rst b/docs/workspace/workspace_bindings.rst → .../workspace/catalog/workspace_bindings.rst
diff --git a/docs/workspace/cluster_policies.rst → docs/workspace/compute/cluster_policies.rst b/docs/workspace/cluster_policies.rst → docs/workspace/compute/cluster_policies.rst
diff --git a/docs/workspace/clusters.rst → docs/workspace/compute/clusters.rst b/docs/workspace/clusters.rst → docs/workspace/compute/clusters.rst
diff --git a/docs/workspace/command_execution.rst → docs/workspace/compute/command_execution.rst b/docs/workspace/command_execution.rst → docs/workspace/compute/command_execution.rst
diff --git a/docs/workspace/global_init_scripts.rst → ...workspace/compute/global_init_scripts.rst b/docs/workspace/global_init_scripts.rst → ...workspace/compute/global_init_scripts.rst
diff --git a/docs/workspace/compute/index.rst b/docs/workspace/compute/index.rst
@@ -0,0 +1,17 @@
+
+Compute
+=======
+
+Use and configure compute for Databricks
+
+.. toctree::
+   :maxdepth: 1
+
+   cluster_policies
+   clusters
+   command_execution
+   global_init_scripts
+   instance_pools
+   instance_profiles
+   libraries
+   policy_families
diff --git a/docs/workspace/instance_pools.rst → docs/workspace/compute/instance_pools.rst b/docs/workspace/instance_pools.rst → docs/workspace/compute/instance_pools.rst
diff --git a/docs/workspace/instance_profiles.rst → docs/workspace/compute/instance_profiles.rst b/docs/workspace/instance_profiles.rst → docs/workspace/compute/instance_profiles.rst
diff --git a/docs/workspace/libraries.rst → docs/workspace/compute/libraries.rst b/docs/workspace/libraries.rst → docs/workspace/compute/libraries.rst
diff --git a/docs/workspace/policy_families.rst → docs/workspace/compute/policy_families.rst b/docs/workspace/policy_families.rst → docs/workspace/compute/policy_families.rst
diff --git a/docs/workspace/workspace-dashboards.rst → docs/workspace/dashboards/index.rst b/docs/workspace/workspace-dashboards.rst → docs/workspace/dashboards/index.rst
@@ -5,6 +5,6 @@ Dashboards
 Manage Lakeview dashboards
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  lakeview
+   lakeview
diff --git a/docs/workspace/lakeview.rst → docs/workspace/dashboards/lakeview.rst b/docs/workspace/lakeview.rst → docs/workspace/dashboards/lakeview.rst
diff --git a/docs/workspace/dbfs.rst → docs/workspace/files/dbfs.rst b/docs/workspace/dbfs.rst → docs/workspace/files/dbfs.rst
diff --git a/docs/workspace/workspace-files.rst → docs/workspace/files/index.rst b/docs/workspace/workspace-files.rst → docs/workspace/files/index.rst
@@ -5,6 +5,6 @@ File Management
 Manage files on Databricks in a filesystem-like interface
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  dbfs
+   dbfs
diff --git a/...orkspace/account_access_control_proxy.rst → ...pace/iam/account_access_control_proxy.rst b/...orkspace/account_access_control_proxy.rst → ...pace/iam/account_access_control_proxy.rst
diff --git a/docs/workspace/current_user.rst → docs/workspace/iam/current_user.rst b/docs/workspace/current_user.rst → docs/workspace/iam/current_user.rst
diff --git a/docs/workspace/groups.rst → docs/workspace/iam/groups.rst b/docs/workspace/groups.rst → docs/workspace/iam/groups.rst
diff --git a/docs/workspace/workspace-iam.rst → docs/workspace/iam/index.rst b/docs/workspace/workspace-iam.rst → docs/workspace/iam/index.rst
@@ -5,11 +5,11 @@ Identity and Access Management
 Manage users, service principals, groups and their permissions in Accounts and Workspaces
 
 .. toctree::
-  :maxdepth: 1
-
-  account_access_control_proxy
-  current_user
-  groups
-  permissions
-  service_principals
-  users
+   :maxdepth: 1
+
+   account_access_control_proxy
+   current_user
+   groups
+   permissions
+   service_principals
+   users
diff --git a/docs/workspace/permissions.rst → docs/workspace/iam/permissions.rst b/docs/workspace/permissions.rst → docs/workspace/iam/permissions.rst
diff --git a/docs/workspace/service_principals.rst → docs/workspace/iam/service_principals.rst b/docs/workspace/service_principals.rst → docs/workspace/iam/service_principals.rst
diff --git a/docs/workspace/users.rst → docs/workspace/iam/users.rst b/docs/workspace/users.rst → docs/workspace/iam/users.rst
diff --git a/docs/workspace/index.rst b/docs/workspace/index.rst
@@ -5,19 +5,19 @@ Workspace APIs
 These APIs are available from WorkspaceClient
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  workspace-workspace
-  workspace-compute
-  workspace-jobs
-  workspace-pipelines
-  workspace-files
-  workspace-ml
-  workspace-serving
-  workspace-iam
-  workspace-sql
-  workspace-catalog
-  workspace-sharing
-  workspace-settings
-  workspace-vectorsearch
-  workspace-dashboards
+   workspace/index
+   compute/index
+   jobs/index
+   pipelines/index
+   files/index
+   ml/index
+   serving/index
+   iam/index
+   sql/index
+   catalog/index
+   sharing/index
+   settings/index
+   vectorsearch/index
+   dashboards/index
diff --git a/docs/workspace/workspace-jobs.rst → docs/workspace/jobs/index.rst b/docs/workspace/workspace-jobs.rst → docs/workspace/jobs/index.rst
@@ -5,6 +5,6 @@ Jobs
 Schedule automated jobs on Databricks Workspaces
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  jobs
+   jobs
diff --git a/docs/workspace/jobs.rst → docs/workspace/jobs/jobs.rst b/docs/workspace/jobs.rst → docs/workspace/jobs/jobs.rst
diff --git a/docs/workspace/experiments.rst → docs/workspace/ml/experiments.rst b/docs/workspace/experiments.rst → docs/workspace/ml/experiments.rst
diff --git a/docs/workspace/workspace-ml.rst → docs/workspace/ml/index.rst b/docs/workspace/workspace-ml.rst → docs/workspace/ml/index.rst
@@ -5,7 +5,7 @@ Machine Learning
 Create and manage experiments, features, and other machine learning artifacts
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  experiments
-  model_registry
+   experiments
+   model_registry
diff --git a/docs/workspace/model_registry.rst → docs/workspace/ml/model_registry.rst b/docs/workspace/model_registry.rst → docs/workspace/ml/model_registry.rst
diff --git a/docs/workspace/workspace-pipelines.rst → docs/workspace/pipelines/index.rst b/docs/workspace/workspace-pipelines.rst → docs/workspace/pipelines/index.rst
@@ -5,6 +5,6 @@ Delta Live Tables
 Manage pipelines, runs, and other Delta Live Table resources
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  pipelines
+   pipelines
diff --git a/docs/workspace/pipelines.rst → docs/workspace/pipelines/pipelines.rst b/docs/workspace/pipelines.rst → docs/workspace/pipelines/pipelines.rst
diff --git a/docs/workspace/apps.rst → docs/workspace/serving/apps.rst b/docs/workspace/apps.rst → docs/workspace/serving/apps.rst
diff --git a/docs/workspace/workspace-serving.rst → docs/workspace/serving/index.rst b/docs/workspace/workspace-serving.rst → docs/workspace/serving/index.rst
@@ -5,7 +5,7 @@ Real-time Serving
 Use real-time inference for machine learning
 
 .. toctree::
-  :maxdepth: 1
+   :maxdepth: 1
 
-  apps
-  serving_endpoints
+   apps
+   serving_endpoints
diff --git a/docs/workspace/serving_endpoints.rst → docs/workspace/serving/serving_endpoints.rst b/docs/workspace/serving_endpoints.rst → docs/workspace/serving/serving_endpoints.rst
diff --git a/docs/workspace/credentials_manager.rst → ...orkspace/settings/credentials_manager.rst b/docs/workspace/credentials_manager.rst → ...orkspace/settings/credentials_manager.rst