Make docs useful again #519
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Screenshot? 😜 |
pietern
approved these changes
Jan 26, 2024
docs/workspace/workspace-catalog.rst
Outdated
There was a problem hiding this comment.
This is a TOC like file, but colocated with the service docs. Same holds for the account dir. Could they be split out (even if they are autogenerated).
tanmay-db
approved these changes
Jan 26, 2024
tanmay-db
added a commit
that referenced
this pull request
Feb 8, 2024
* Make docs useful again ([#519](#519)). * Show undocumented fields in dataclasses ([#520](#520)). * Search for both databricks.exe and databricks binaries in windows ([#517](#517)). * Rename `databricks.sdk.errors.mapping` to `databricks.sdk.errors.platform` ([#522](#522)). * refactor: add Union to content (2nd) parameter in upload function ([#493](#493)). * Regenerate from the tip of main ([#524](#524)). * Fix WorkspaceConf.get_status and WorkspaceConf.set_status ([#525](#525)). * Enable Databricks OAuth also for Azure and GCP ([#526](#526)). * Construct workspace client from account client ([#527](#527)). * Skip test_get_workspace_client in Azure and GCP ([#531](#531)). * Do not terminate listing for token-based pagination resources on empty response ([#530](#530)). * Use fake clock for faster unit tests ([#533](#533)). * Generate SDK ([#536](#536)). API Changes: * Added `cancel_refresh()` method for [w.lakehouse_monitors](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/lakehouse_monitors.html) workspace-level service. * Added `get_refresh()` method for [w.lakehouse_monitors](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/lakehouse_monitors.html) workspace-level service. * Added `list_refreshes()` method for [w.lakehouse_monitors](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/lakehouse_monitors.html) workspace-level service. * Added `run_refresh()` method for [w.lakehouse_monitors](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/lakehouse_monitors.html) workspace-level service. * Removed `name` field for `databricks.sdk.service.catalog.UpdateConnection`. * Removed `name` field for `databricks.sdk.service.catalog.UpdateMetastore`. * Removed `name` field for `databricks.sdk.service.catalog.UpdateRegisteredModelRequest`. * Removed `name` field for `databricks.sdk.service.catalog.UpdateSchema`. * Removed `name` field for `databricks.sdk.service.catalog.UpdateVolumeRequestContent`. * Added `databricks.sdk.service.catalog.CancelRefreshRequest` dataclass. * Added `databricks.sdk.service.catalog.GetRefreshRequest` dataclass. * Added `databricks.sdk.service.catalog.ListRefreshesRequest` dataclass. * Added `databricks.sdk.service.catalog.MonitorRefreshInfo` dataclass. * Added `databricks.sdk.service.catalog.MonitorRefreshInfoState` dataclass. * Added `databricks.sdk.service.catalog.RunRefreshRequest` dataclass. * Changed `max_workers` field for `databricks.sdk.service.compute.AutoScale` to no longer be required. * Changed `min_workers` field for `databricks.sdk.service.compute.AutoScale` to no longer be required. * Changed `destination` field for `databricks.sdk.service.compute.DbfsStorageInfo` to be required. * Added `use_preemptible_executors` field for `databricks.sdk.service.compute.GcpAttributes`. * Added `zone_id` field for `databricks.sdk.service.compute.GcpAttributes`. * Added `abfss` field for `databricks.sdk.service.compute.InitScriptInfo`. * Added `gcs` field for `databricks.sdk.service.compute.InitScriptInfo`. * Changed `destination` field for `databricks.sdk.service.compute.LocalFileInfo` to be required. * Changed `destination` field for `databricks.sdk.service.compute.S3StorageInfo` to be required. * Changed `destination` field for `databricks.sdk.service.compute.VolumesStorageInfo` to be required. * Changed `clients` field for `databricks.sdk.service.compute.WorkloadType` to be required. * Changed `destination` field for `databricks.sdk.service.compute.WorkspaceStorageInfo` to be required. * Added `databricks.sdk.service.compute.Adlsgen2Info` dataclass. * Added `databricks.sdk.service.compute.GcsStorageInfo` dataclass. * Removed `get_status()` method for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. * Added `create_directory()` method for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. * Added `delete_directory()` method for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. * Added `list_directory_contents()` method for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. * Added `databricks.sdk.service.files.CreateDirectoryRequest` dataclass. * Added `databricks.sdk.service.files.DeleteDirectoryRequest` dataclass. * Added `databricks.sdk.service.files.DirectoryEntry` dataclass. * Added `databricks.sdk.service.files.ListDirectoryContentsRequest` dataclass. * Added `databricks.sdk.service.files.ListDirectoryResponse` dataclass. * Added `databricks.sdk.service.files.PageToken` dataclass. * Added `source` field for `databricks.sdk.service.jobs.DbtTask`. * Added `for_each_task` field for `databricks.sdk.service.jobs.RunTask`. * Added `source` field for `databricks.sdk.service.jobs.SqlTaskFile`. * Added `for_each_task` field for `databricks.sdk.service.jobs.SubmitTask`. * Added `for_each_task` field for `databricks.sdk.service.jobs.Task`. * Added `databricks.sdk.service.jobs.ForEachStats` dataclass. * Added `databricks.sdk.service.jobs.ForEachTask` dataclass. * Added `databricks.sdk.service.jobs.ForEachTaskErrorMessageStats` dataclass. * Added `databricks.sdk.service.jobs.ForEachTaskTaskRunStats` dataclass. * Added `databricks.sdk.service.jobs.RunForEachTask` dataclass. * Removed `reset()` method for [w.pipelines](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/pipelines.html) workspace-level service. * Changed `autoscale` field for `databricks.sdk.service.pipelines.PipelineCluster` to `databricks.sdk.service.pipelines.PipelineClusterAutoscale` dataclass. * Removed `databricks.sdk.service.pipelines.ResetRequest` dataclass. * Added `databricks.sdk.service.pipelines.PipelineClusterAutoscale` dataclass. * Added `databricks.sdk.service.pipelines.PipelineClusterAutoscaleMode` dataclass. * Changed `delete_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service with new required argument order. * Removed `read_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service. * Changed `update_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service with new required argument order. * Added `get_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service. * Removed `delete_default_workspace_namespace()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Removed `read_default_workspace_namespace()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Removed `update_default_workspace_namespace()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `delete_default_namespace_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `delete_restrict_workspace_admins_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `get_default_namespace_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `get_restrict_workspace_admins_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `update_default_namespace_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `update_restrict_workspace_admins_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Removed `databricks.sdk.service.settings.DeleteDefaultWorkspaceNamespaceRequest` dataclass. * Removed `databricks.sdk.service.settings.DeleteDefaultWorkspaceNamespaceResponse` dataclass. * Changed `etag` field for `databricks.sdk.service.settings.DeletePersonalComputeSettingRequest` to no longer be required. * Removed `databricks.sdk.service.settings.ReadDefaultWorkspaceNamespaceRequest` dataclass. * Removed `databricks.sdk.service.settings.ReadPersonalComputeSettingRequest` dataclass. * Removed `databricks.sdk.service.settings.UpdateDefaultWorkspaceNamespaceRequest` dataclass. * Changed `allow_missing` field for `databricks.sdk.service.settings.UpdatePersonalComputeSettingRequest` to be required. * Changed `setting` field for `databricks.sdk.service.settings.UpdatePersonalComputeSettingRequest` to be required. * Added `field_mask` field for `databricks.sdk.service.settings.UpdatePersonalComputeSettingRequest`. * Added `databricks.sdk.service.settings.DeleteDefaultNamespaceSettingRequest` dataclass. * Added `databricks.sdk.service.settings.DeleteDefaultNamespaceSettingResponse` dataclass. * Added `databricks.sdk.service.settings.DeleteRestrictWorkspaceAdminsSettingRequest` dataclass. * Added `databricks.sdk.service.settings.DeleteRestrictWorkspaceAdminsSettingResponse` dataclass. * Added `databricks.sdk.service.settings.GetDefaultNamespaceSettingRequest` dataclass. * Added `databricks.sdk.service.settings.GetPersonalComputeSettingRequest` dataclass. * Added `databricks.sdk.service.settings.GetRestrictWorkspaceAdminsSettingRequest` dataclass. * Added `databricks.sdk.service.settings.RestrictWorkspaceAdminsMessage` dataclass. * Added `databricks.sdk.service.settings.RestrictWorkspaceAdminsMessageStatus` dataclass. * Added `databricks.sdk.service.settings.RestrictWorkspaceAdminsSetting` dataclass. * Added `databricks.sdk.service.settings.UpdateDefaultNamespaceSettingRequest` dataclass. * Added `databricks.sdk.service.settings.UpdateRestrictWorkspaceAdminsSettingRequest` dataclass. * Removed `delta_sync_vector_index_spec` field for `databricks.sdk.service.vectorsearch.CreateVectorIndexRequest`. * Added `delta_sync_index_spec` field for `databricks.sdk.service.vectorsearch.CreateVectorIndexRequest`. * Added `file_type` field for `databricks.sdk.service.workspace.ExportResponse`. * Added `resource_id` field for `databricks.sdk.service.workspace.ObjectInfo`. OpenAPI SHA: 6b897bc95b23abed8b9f5eff0e6b8ec034046180, Date: 2024-02-08
Merged
github-merge-queue bot
pushed a commit
that referenced
this pull request
Feb 9, 2024
## 0.19.0 ### Improvements and Bug Fixes * Construct workspace client from account client ([#527](#527)). * Enabled Databricks OAuth also for Azure and GCP ([#526](#526)). * Do not terminate listing for token-based pagination resources on empty response ([#530](#530)). * Renamed `databricks.sdk.errors.mapping` to `databricks.sdk.errors.platform` ([#522](#522)). * Added Union to content (2nd) parameter in upload function ([#493](#493)). * Fixed WorkspaceConf.get_status and WorkspaceConf.set_status ([#525](#525)). ### Documentation * Make docs useful again ([#519](#519)). * Show undocumented fields in dataclasses ([#520](#520)). ### API Changes Additions: * Added the following dataclasses: - `databricks.sdk.service.catalog.CancelRefreshRequest` - `databricks.sdk.service.catalog.GetRefreshRequest` - `databricks.sdk.service.catalog.ListRefreshesRequest` - `databricks.sdk.service.catalog.MonitorRefreshInfo` - `databricks.sdk.service.catalog.MonitorRefreshInfoState` - `databricks.sdk.service.catalog.RunRefreshRequest` - `databricks.sdk.service.compute.Adlsgen2Info` - `databricks.sdk.service.compute.GcsStorageInfo` - `databricks.sdk.service.files.CreateDirectoryRequest` - `databricks.sdk.service.files.DeleteDirectoryRequest` - `databricks.sdk.service.files.DirectoryEntry` - `databricks.sdk.service.files.ListDirectoryContentsRequest` - `databricks.sdk.service.files.ListDirectoryResponse` - `databricks.sdk.service.files.PageToken` - `databricks.sdk.service.jobs.ForEachStats` - `databricks.sdk.service.jobs.ForEachTask` - `databricks.sdk.service.jobs.ForEachTaskErrorMessageStats` - `databricks.sdk.service.jobs.ForEachTaskTaskRunStats` - `databricks.sdk.service.jobs.RunForEachTask` - `databricks.sdk.service.pipelines.PipelineClusterAutoscale` - `databricks.sdk.service.pipelines.PipelineClusterAutoscaleMode` - `databricks.sdk.service.settings.DeleteDefaultNamespaceSettingRequest` - `databricks.sdk.service.settings.DeleteDefaultNamespaceSettingResponse` - `databricks.sdk.service.settings.DeleteRestrictWorkspaceAdminsSettingRequest` - `databricks.sdk.service.settings.DeleteRestrictWorkspaceAdminsSettingResponse` - `databricks.sdk.service.settings.GetDefaultNamespaceSettingRequest` - `databricks.sdk.service.settings.GetPersonalComputeSettingRequest` - `databricks.sdk.service.settings.GetRestrictWorkspaceAdminsSettingRequest` - `databricks.sdk.service.settings.RestrictWorkspaceAdminsMessage` - `databricks.sdk.service.settings.RestrictWorkspaceAdminsMessageStatus` - `databricks.sdk.service.settings.RestrictWorkspaceAdminsSetting` - `databricks.sdk.service.settings.UpdateDefaultNamespaceSettingRequest` - `databricks.sdk.service.settings.UpdateRestrictWorkspaceAdminsSettingRequest` * Added `cancel_refresh()`, `get_refresh()`, `list_refreshes()` and `run_refresh()` method for [w.lakehouse_monitors](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/lakehouse_monitors.html) workspace-level service. * Added `use_preemptible_executors` field for `databricks.sdk.service.compute.GcpAttributes`. * Added `zone_id` field for `databricks.sdk.service.compute.GcpAttributes`. * Added `abfss` and `gcs` field for `databricks.sdk.service.compute.InitScriptInfo`. * Added `create_directory()`, `delete_directory()` and `list_directory_contents()` method for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. * Added `source` field for `databricks.sdk.service.jobs.DbtTask` and `databricks.sdk.service.jobs.SqlTaskFile`. * Added `for_each_task` field for `databricks.sdk.service.jobs.RunTask`, `databricks.sdk.service.jobs.SubmitTask` and `databricks.sdk.service.jobs.Task`. * Added `field_mask` field for `databricks.sdk.service.settings.UpdatePersonalComputeSettingRequest`. * Added `delta_sync_index_spec` field for `databricks.sdk.service.vectorsearch.CreateVectorIndexRequest`. * Added `file_type` field for `databricks.sdk.service.workspace.ExportResponse`. * Added `resource_id` field for `databricks.sdk.service.workspace.ObjectInfo`. * Added `delete_default_namespace_setting()`, `delete_restrict_workspace_admins_setting()`, `get_default_namespace_setting()`, `get_restrict_workspace_admins_setting()`, `update_default_namespace_setting()` and `update_restrict_workspace_admins_setting()` method for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. * Added `get_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service. Removals: * Removed the following dataclasses: - `databricks.sdk.service.settings.ReadDefaultWorkspaceNamespaceRequest` - `databricks.sdk.service.settings.ReadPersonalComputeSettingRequest` - `databricks.sdk.service.settings.UpdateDefaultWorkspaceNamespaceRequest` - `databricks.sdk.service.settings.DeleteDefaultWorkspaceNamespaceRequest` - `databricks.sdk.service.settings.DeleteDefaultWorkspaceNamespaceResponse` - `databricks.sdk.service.pipelines.ResetRequest` * Removed the following methods: - `get_status()` for [w.files](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/files.html) workspace-level service. - `reset()` for [w.pipelines](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/pipelines.html) workspace-level service. - `delete_default_workspace_namespace()` for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. - `read_default_workspace_namespace()` for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. - `update_default_workspace_namespace()` for [w.settings](https://databricks-sdk-py.readthedocs.io/en/latest/workspace/settings.html) workspace-level service. - `read_personal_compute_setting()` for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service. * Removed `name` field for `databricks.sdk.service.catalog.UpdateConnection`, `databricks.sdk.service.catalog.UpdateMetastore`, `databricks.sdk.service.catalog.UpdateRegisteredModelRequest`. `databricks.sdk.service.catalog.UpdateSchema`and `databricks.sdk.service.catalog.UpdateVolumeRequestContent`. * Removed `delta_sync_vector_index_spec` field for `databricks.sdk.service.vectorsearch.CreateVectorIndexRequest`. Changes: * Changed `max_workers` and `min_workers` field for `databricks.sdk.service.compute.AutoScale` to no longer be required. * Changed `destination` field for `databricks.sdk.service.compute.DbfsStorageInfo`, `databricks.sdk.service.compute.LocalFileInfo`, `databricks.sdk.service.compute.S3StorageInfo`, `databricks.sdk.service.compute.VolumesStorageInfo` and `databricks.sdk.service.compute.WorkspaceStorageInfo` to be required. * Changed `clients` field for `databricks.sdk.service.compute.WorkloadType` to be required. * Changed `allow_missing` and `setting` field for `databricks.sdk.service.settings.UpdatePersonalComputeSettingRequest` to be required. * Changed `etag` field for `databricks.sdk.service.settings.DeletePersonalComputeSettingRequest` to no longer be required. * Changed `autoscale` field for `databricks.sdk.service.pipelines.PipelineCluster` to `databricks.sdk.service.pipelines.PipelineClusterAutoscale` dataclass. * Changed `delete_personal_compute_setting()` and `update_personal_compute_setting()` method for [a.account_settings](https://databricks-sdk-py.readthedocs.io/en/latest/account/account_settings.html) account-level service with new required argument order. ### Internal Changes * Generate SDK ([#536](#536)). * Use fake clock for faster unit tests ([#533](#533)). * Skip test_get_workspace_client in Azure and GCP ([#531](#531)). * Regenerate from the tip of main ([#524](#524)). * Search for both databricks.exe and databricks binaries in windows ([#517](#517)). OpenAPI SHA: 6b897bc95b23abed8b9f5eff0e6b8ec034046180, Date: 2024-02-08
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
The last refactor to docs introduced dataclasses and enum documentation but regressed on examples and ease of use/navigability by introducing extremely long pages with many different APIs and classes documented. This has led to some confusion for users of the SDK who are simply trying to explore/understand what functionality is supported.
This PR undoes that refactor while preserving the dataclass and enum documentation, and it even improves on it somewhat, reducing a substantial amount of visual noise from dataclass constructor signatures and making enum values easier to read and understand.
Link to preview: https://databricks-sdk-py--519.org.readthedocs.build/en/519/
Tests
make testrun locallymake fmtapplied