more fixes

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

Hide file tree

Showing 92 changed files with 221 additions and 182 deletions.
diff --git a/docs/account/access_control.rst b/docs/account/access_control.rst
@@ -1,5 +1,5 @@
-Account Access Control
-======================
+``a.access_control``: Account Access Control
+============================================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: AccountAccessControlAPI

diff --git a/docs/account/billable_usage.rst b/docs/account/billable_usage.rst
@@ -1,5 +1,5 @@
-Billable usage download
-=======================
+``a.billable_usage``: Billable usage download
+=============================================
 .. currentmodule:: databricks.sdk.service.billing
 
 .. py:class:: BillableUsageAPI

diff --git a/docs/account/budgets.rst b/docs/account/budgets.rst
@@ -1,5 +1,5 @@
-Budgets
-=======
+``a.budgets``: Budgets
+======================
 .. currentmodule:: databricks.sdk.service.billing
 
 .. py:class:: BudgetsAPI

diff --git a/docs/account/credentials.rst b/docs/account/credentials.rst
@@ -1,5 +1,5 @@
-Credential configurations
-=========================
+``a.credentials``: Credential configurations
+============================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: CredentialsAPI

diff --git a/docs/account/custom_app_integration.rst b/docs/account/custom_app_integration.rst
@@ -1,5 +1,5 @@
-OAuth Custom App Integration
-============================
+``a.custom_app_integration``: OAuth Custom App Integration
+==========================================================
 .. currentmodule:: databricks.sdk.service.oauth2
 
 .. py:class:: CustomAppIntegrationAPI

diff --git a/docs/account/encryption_keys.rst b/docs/account/encryption_keys.rst
@@ -1,5 +1,5 @@
-Key configurations
-==================
+``a.encryption_keys``: Key configurations
+=========================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: EncryptionKeysAPI

diff --git a/docs/account/groups.rst b/docs/account/groups.rst
@@ -1,5 +1,5 @@
-Account Groups
-==============
+``a.groups``: Account Groups
+============================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: AccountGroupsAPI

diff --git a/docs/account/ip_access_lists.rst b/docs/account/ip_access_lists.rst
@@ -1,5 +1,5 @@
-Account IP Access Lists
-=======================
+``a.ip_access_lists``: Account IP Access Lists
+==============================================
 .. currentmodule:: databricks.sdk.service.settings
 
 .. py:class:: AccountIpAccessListsAPI

diff --git a/docs/account/log_delivery.rst b/docs/account/log_delivery.rst
@@ -1,5 +1,5 @@
-Log delivery configurations
-===========================
+``a.log_delivery``: Log delivery configurations
+===============================================
 .. currentmodule:: databricks.sdk.service.billing
 
 .. py:class:: LogDeliveryAPI

diff --git a/docs/account/metastore_assignments.rst b/docs/account/metastore_assignments.rst
@@ -1,5 +1,5 @@
-Account Metastore Assignments
-=============================
+``a.metastore_assignments``: Account Metastore Assignments
+==========================================================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: AccountMetastoreAssignmentsAPI

diff --git a/docs/account/metastores.rst b/docs/account/metastores.rst
@@ -1,5 +1,5 @@
-Account Metastores
-==================
+``a.metastores``: Account Metastores
+====================================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: AccountMetastoresAPI

diff --git a/docs/account/network_connectivity.rst b/docs/account/network_connectivity.rst
@@ -1,5 +1,5 @@
-Network Connectivity
-====================
+``a.network_connectivity``: Network Connectivity
+================================================
 .. currentmodule:: databricks.sdk.service.settings
 
 .. py:class:: NetworkConnectivityAPI

diff --git a/docs/account/networks.rst b/docs/account/networks.rst
@@ -1,5 +1,5 @@
-Network configurations
-======================
+``a.networks``: Network configurations
+======================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: NetworksAPI

diff --git a/docs/account/o_auth_published_apps.rst b/docs/account/o_auth_published_apps.rst
@@ -1,5 +1,5 @@
-OAuth Published App
-===================
+``a.o_auth_published_apps``: OAuth Published App
+================================================
 .. currentmodule:: databricks.sdk.service.oauth2
 
 .. py:class:: OAuthPublishedAppsAPI

diff --git a/docs/account/private_access.rst b/docs/account/private_access.rst
@@ -1,5 +1,5 @@
-Private Access Settings
-=======================
+``a.private_access``: Private Access Settings
+=============================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: PrivateAccessAPI

diff --git a/docs/account/published_app_integration.rst b/docs/account/published_app_integration.rst
@@ -1,5 +1,5 @@
-OAuth Published App Integration
-===============================
+``a.published_app_integration``: OAuth Published App Integration
+================================================================
 .. currentmodule:: databricks.sdk.service.oauth2
 
 .. py:class:: PublishedAppIntegrationAPI

diff --git a/docs/account/service_principal_secrets.rst b/docs/account/service_principal_secrets.rst
@@ -1,5 +1,5 @@
-Service Principal Secrets
-=========================
+``a.service_principal_secrets``: Service Principal Secrets
+==========================================================
 .. currentmodule:: databricks.sdk.service.oauth2
 
 .. py:class:: ServicePrincipalSecretsAPI

diff --git a/docs/account/service_principals.rst b/docs/account/service_principals.rst
@@ -1,5 +1,5 @@
-Account Service Principals
-==========================
+``a.service_principals``: Account Service Principals
+====================================================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: AccountServicePrincipalsAPI

diff --git a/docs/account/settings.rst b/docs/account/settings.rst
@@ -1,5 +1,5 @@
-Personal Compute Enablement
-===========================
+``a.settings``: Personal Compute Enablement
+===========================================
 .. currentmodule:: databricks.sdk.service.settings
 
 .. py:class:: AccountSettingsAPI

diff --git a/docs/account/storage.rst b/docs/account/storage.rst
@@ -1,5 +1,5 @@
-Storage configurations
-======================
+``a.storage``: Storage configurations
+=====================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: StorageAPI

diff --git a/docs/account/storage_credentials.rst b/docs/account/storage_credentials.rst
@@ -1,5 +1,5 @@
-Account Storage Credentials
-===========================
+``a.storage_credentials``: Account Storage Credentials
+======================================================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: AccountStorageCredentialsAPI

diff --git a/docs/account/users.rst b/docs/account/users.rst
@@ -1,5 +1,5 @@
-Account Users
-=============
+``a.users``: Account Users
+==========================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: AccountUsersAPI

diff --git a/docs/account/vpc_endpoints.rst b/docs/account/vpc_endpoints.rst
@@ -1,5 +1,5 @@
-VPC Endpoint Configurations
-===========================
+``a.vpc_endpoints``: VPC Endpoint Configurations
+================================================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: VpcEndpointsAPI

diff --git a/docs/account/workspace_assignment.rst b/docs/account/workspace_assignment.rst
@@ -1,5 +1,5 @@
-Workspace Assignment
-====================
+``a.workspace_assignment``: Workspace Assignment
+================================================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: WorkspaceAssignmentAPI

diff --git a/docs/account/workspaces.rst b/docs/account/workspaces.rst
@@ -1,5 +1,5 @@
-Workspaces
-==========
+``a.workspaces``: Workspaces
+============================
 .. currentmodule:: databricks.sdk.service.provisioning
 
 .. py:class:: WorkspacesAPI

diff --git a/docs/gen-client-docs.py b/docs/gen-client-docs.py
@@ -81,6 +81,7 @@ def as_rst(self, usage) -> str:
 
 @dataclass
 class ServiceDoc:
+    client_prefix: str
     service_name: str
     class_name: str
     methods: list[MethodDoc]
@@ -90,8 +91,9 @@ class ServiceDoc:
     def as_rst(self) -> str:
         if not self.doc:
             self.doc = ''
+        title = f'``{self.client_prefix}.{self.service_name}``: {self.tag.name}'
         out = [
-            self.tag.name, '=' * len(self.tag.name),
+            title, '=' * len(title),
             f'.. currentmodule:: databricks.sdk.service.{self.tag.package.name}', '',
             f'.. py:class:: {self.class_name}', '', f'    {self.doc}'
         ]
@@ -274,6 +276,7 @@ def class_methods(self, inst) -> list[MethodDoc]:
         return method_docs
 
     def service_docs(self, client_inst) -> list[ServiceDoc]:
+        client_prefix = 'w' if isinstance(client_inst, WorkspaceClient) else 'a'
         ignore_client_fields = ('config', 'dbutils', 'api_client', 'files')
         all = []
         for service_name, service_inst in inspect.getmembers(client_inst):
@@ -284,7 +287,8 @@ def service_docs(self, client_inst) -> list[ServiceDoc]:
             class_doc = service_inst.__doc__
             class_name = service_inst.__class__.__name__
             all.append(
-                ServiceDoc(service_name=service_name,
+                ServiceDoc(client_prefix=client_prefix,
+                           service_name=service_name,
                            class_name=class_name,
                            doc=class_doc,
                            tag=self._get_tag_name(service_inst.__class__.__name__, service_name),

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -20,6 +20,41 @@ followed by
 dbutils.library.restartPython()
 ```
 
+## Usage Overview
+
+At its core, the SDK exposes two primary clients: `databricks.sdk.WorkspaceClient` and `databricks.sdk.AccountClient`. The `WorkspaceClient` is tailored for interacting with resources within the Databricks workspace, such as notebooks, jobs, and clusters, while the `AccountClient` focuses on account-level functionalities including user and group management, billing, and workspace provisioning and management.
+
+To use the SDK to call an API, first find the API in either the [Workspace API Reference](workspace/index.rst) or [Account API reference](account/index.rst). Then, on the appropriate client, call the corresponding method. All API calls have the form
+
+```
+w.<SERVICE>.<METHOD>(<parameters>)
+```
+or
+```
+a.<SERVICE>.<METHOD>(parameters)
+```
+
+For example, to list all SQL queries in the workspace, run:
+
+```python
+# Authenticate as described above
+from databricks.sdk import WorkspaceClient
+w = WorkspaceClient()
+for query in w.queries.list():
+    print(f'query {query.name} was created at {query.created_at}')
+```
+
+To list all workspaces in the account, run:
+
+```python
+# Authenticate as described above
+from databricks.sdk import AccountClient
+a = AccountClient()
+for workspace in a.workspaces.list():
+    print(f'workspace {workspace.workspace_name} was created at {workspace.creation_time}')
+```
+
+
 ## Authentication
 
 There are two primary entry points to the Databricks SDK:

diff --git a/docs/workspace/account_access_control_proxy.rst b/docs/workspace/account_access_control_proxy.rst
@@ -1,5 +1,5 @@
-Account Access Control Proxy
-============================
+``w.account_access_control_proxy``: Account Access Control Proxy
+================================================================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: AccountAccessControlProxyAPI

diff --git a/docs/workspace/alerts.rst b/docs/workspace/alerts.rst
@@ -1,5 +1,5 @@
-Alerts
-======
+``w.alerts``: Alerts
+====================
 .. currentmodule:: databricks.sdk.service.sql
 
 .. py:class:: AlertsAPI

diff --git a/docs/workspace/apps.rst b/docs/workspace/apps.rst
@@ -1,5 +1,5 @@
-Databricks Apps
-===============
+``w.apps``: Databricks Apps
+===========================
 .. currentmodule:: databricks.sdk.service.serving
 
 .. py:class:: AppsAPI

diff --git a/docs/workspace/artifact_allowlists.rst b/docs/workspace/artifact_allowlists.rst
@@ -1,5 +1,5 @@
-Artifact Allowlists
-===================
+``w.artifact_allowlists``: Artifact Allowlists
+==============================================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: ArtifactAllowlistsAPI

diff --git a/docs/workspace/catalogs.rst b/docs/workspace/catalogs.rst
@@ -1,5 +1,5 @@
-Catalogs
-========
+``w.catalogs``: Catalogs
+========================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: CatalogsAPI

diff --git a/docs/workspace/clean_rooms.rst b/docs/workspace/clean_rooms.rst
@@ -1,5 +1,5 @@
-Clean Rooms
-===========
+``w.clean_rooms``: Clean Rooms
+==============================
 .. currentmodule:: databricks.sdk.service.sharing
 
 .. py:class:: CleanRoomsAPI

diff --git a/docs/workspace/cluster_policies.rst b/docs/workspace/cluster_policies.rst
@@ -1,5 +1,5 @@
-Cluster Policies
-================
+``w.cluster_policies``: Cluster Policies
+========================================
 .. currentmodule:: databricks.sdk.service.compute
 
 .. py:class:: ClusterPoliciesAPI

diff --git a/docs/workspace/clusters.rst b/docs/workspace/clusters.rst
@@ -1,5 +1,5 @@
-Clusters
-========
+``w.clusters``: Clusters
+========================
 .. currentmodule:: databricks.sdk.service.compute
 
 .. py:class:: ClustersExt

diff --git a/docs/workspace/command_execution.rst b/docs/workspace/command_execution.rst
@@ -1,5 +1,5 @@
-Command Execution
-=================
+``w.command_execution``: Command Execution
+==========================================
 .. currentmodule:: databricks.sdk.service.compute
 
 .. py:class:: CommandExecutionAPI

diff --git a/docs/workspace/connections.rst b/docs/workspace/connections.rst
@@ -1,5 +1,5 @@
-Connections
-===========
+``w.connections``: Connections
+==============================
 .. currentmodule:: databricks.sdk.service.catalog
 
 .. py:class:: ConnectionsAPI

diff --git a/docs/workspace/credentials_manager.rst b/docs/workspace/credentials_manager.rst
@@ -1,5 +1,5 @@
-Credentials Manager
-===================
+``w.credentials_manager``: Credentials Manager
+==============================================
 .. currentmodule:: databricks.sdk.service.settings
 
 .. py:class:: CredentialsManagerAPI

diff --git a/docs/workspace/current_user.rst b/docs/workspace/current_user.rst
@@ -1,5 +1,5 @@
-CurrentUser
-===========
+``w.current_user``: CurrentUser
+===============================
 .. currentmodule:: databricks.sdk.service.iam
 
 .. py:class:: CurrentUserAPI

diff --git a/docs/workspace/dashboard_widgets.rst b/docs/workspace/dashboard_widgets.rst
@@ -1,5 +1,5 @@
-Dashboard Widgets
-=================
+``w.dashboard_widgets``: Dashboard Widgets
+==========================================
 .. currentmodule:: databricks.sdk.service.sql
 
 .. py:class:: DashboardWidgetsAPI

diff --git a/docs/workspace/dashboards.rst b/docs/workspace/dashboards.rst
@@ -1,5 +1,5 @@
-Dashboards
-==========
+``w.dashboards``: Dashboards
+============================
 .. currentmodule:: databricks.sdk.service.sql
 
 .. py:class:: DashboardsAPI

diff --git a/docs/workspace/data_sources.rst b/docs/workspace/data_sources.rst
@@ -1,5 +1,5 @@
-Data Sources
-============
+``w.data_sources``: Data Sources
+================================
 .. currentmodule:: databricks.sdk.service.sql
 
 .. py:class:: DataSourcesAPI