docs(datalab): improve the API documentation wording (#1546)

Author: scaleway-bot

scaleway-async/scaleway_async/datalab/v1beta1/api.py

@@ -72,15 +72,15 @@ async def create_datalab(
         Create a new Data Lab. In this call, one can personalize the node counts, add a notebook, choose the private network, define the persistent volume storage capacity.
         :param name: The name of the Data Lab.
         :param description: The description of the Data Lab.
-        :param has_notebook: Whether a JupyterLab notebook shall be created with the Data Lab or not.
+        :param has_notebook: Select this option to include a notebook as part of the Data Lab.
         :param spark_version: The version of Spark running inside the Data Lab, available options can be viewed at ListClusterVersions.
-        :param private_network_id: The private network to which the Data Lab is connected. Important for accessing the Spark Master URL from a private cluster.
+        :param private_network_id: The unique identifier of the private network the Data Lab will be attached to.
         :param region: Region to target. If none is passed will use default region from the config.
         :param project_id: The unique identifier of the project where the Data Lab will be created.
         :param tags: The tags of the Data Lab.
-        :param main: The Spark main node configuration of the Data Lab, has one parameter `node_type` which specifies the compute node type of the main node. See ListNodeTypes for available options.
-        :param worker: The Spark worker node configuration of the Data Lab, has two parameters `node_type` for selecting the type of the worker node, and `node_count` for specifying the amount of nodes.
-        :param total_storage: The total storage selected by the user for Spark workers. This means the workers will not use more then this amount for their workload.
+        :param main: The cluster main node specification. It holds the parameters `node_type` which specifies the node type of the main node. See ListNodeTypes for available options. See ListNodeTypes for available options.
+        :param worker: The cluster worker node specification. It holds the parameters `node_type` which specifies the node type of the worker node and `node_count` for specifying the amount of nodes.
+        :param total_storage: The maximum persistent volume storage that will be available during workload.
         :return: :class:`Datalab <Datalab>`
 
         Usage:
@@ -386,12 +386,12 @@ async def list_node_types(
         resource_type: Optional[ListNodeTypesRequestResourceType] = None,
     ) -> ListNodeTypesResponse:
         """
-        List the available compute node types upon which a Data Lab can be created.
+        List the available compute node types for creating a Data Lab.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
         :param order_by: The order by field. Available fields are `name_asc`, `name_desc`, `vcpus_asc`, `vcpus_desc`, `memory_gigabytes_asc`, `memory_gigabytes_desc`, `vram_bytes_asc`, `vram_bytes_desc`, `gpus_asc`, `gpus_desc`.
-        :param targets: Filter on the wanted targets, whether it's for main node or worker.
+        :param targets: Filter based on the target of the nodes. Allows to filter the nodes based on their purpose which can be main or worker node.
         :param resource_type: Filter based on node type ( `cpu`/`gpu`/`all` ).
         :return: :class:`ListNodeTypesResponse <ListNodeTypesResponse>`
 
@@ -431,12 +431,12 @@ async def list_node_types_all(
         resource_type: Optional[ListNodeTypesRequestResourceType] = None,
     ) -> list[NodeType]:
         """
-        List the available compute node types upon which a Data Lab can be created.
+        List the available compute node types for creating a Data Lab.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
         :param order_by: The order by field. Available fields are `name_asc`, `name_desc`, `vcpus_asc`, `vcpus_desc`, `memory_gigabytes_asc`, `memory_gigabytes_desc`, `vram_bytes_asc`, `vram_bytes_desc`, `gpus_asc`, `gpus_desc`.
-        :param targets: Filter on the wanted targets, whether it's for main node or worker.
+        :param targets: Filter based on the target of the nodes. Allows to filter the nodes based on their purpose which can be main or worker node.
         :param resource_type: Filter based on node type ( `cpu`/`gpu`/`all` ).
         :return: :class:`list[NodeType] <list[NodeType]>`
 
@@ -469,7 +469,7 @@ async def list_notebook_versions(
         order_by: Optional[ListNotebookVersionsRequestOrderBy] = None,
     ) -> ListNotebookVersionsResponse:
         """
-        List available notebook versions.
+        Lists available notebook versions.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
@@ -508,7 +508,7 @@ async def list_notebook_versions_all(
         order_by: Optional[ListNotebookVersionsRequestOrderBy] = None,
     ) -> list[Notebook]:
         """
-        List available notebook versions.
+        Lists available notebook versions.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.

scaleway-async/scaleway_async/datalab/v1beta1/types.py

@@ -250,7 +250,7 @@ class Datalab:
 
     project_id: str
     """
-    The identifier of the project where the Data Lab has been created.
+    The unique identifier of the project where the Data Lab has been created.
     """
 
     name: str
@@ -270,7 +270,7 @@ class Datalab:
 
     status: DatalabStatus
     """
-    The status of the Data Lab. For a working Data Lab this should be `ready`.
+    The status of the Data Lab. For a working Data Lab the status is marked as `ready`.
     """
 
     region: ScwRegion
@@ -290,17 +290,17 @@ class Datalab:
 
     private_network_id: str
     """
-    The private network to which the data lab is connected. This is important for accessing the Spark Master URL.
+    The unique identifier of the private network to which the Data Lab is attached to.
     """
 
     main: Optional[DatalabSparkMain] = None
     """
-    The Spark Main node specification of Data lab. It holds the parameters `node_type` the compute node type of the main node, `spark_ui_url` where the Spark UI is available, `spark_master_url` with which one can connect to the cluster from within one's VPC, `root_volume` the size of the volume assigned to the main node.
+    The Spark Main node specification of Data lab. It holds the parameters `node_type`, `spark_ui_url` (available to reach Spark UI), `spark_master_url` (used to reach the cluster within a VPC), `root_volume` (size of the volume assigned to the cluster).
     """
 
     worker: Optional[DatalabSparkWorker] = None
     """
-    The worker node specification of the Data Lab. It presents the parameters `node_type` the compute node type of each worker node, `node_count` the number of worker nodes currently in the cluster, `root_volume` the root volume size of each executor.
+    The cluster worker nodes specification. It holds the parameters `node_type`, `node_count`, `root_volume` (size of the volume assigned to the cluster).
     """
 
     created_at: Optional[datetime] = None
@@ -315,17 +315,17 @@ class Datalab:
 
     notebook_url: Optional[str] = None
     """
-    The URL of said notebook if exists.
+    The URL of the notebook if available.
     """
 
     total_storage: Optional[Volume] = None
     """
-    The total storage selected by the user for Spark.
+    The total persistent volume storage selected to run Spark.
     """
 
     notebook_master_url: Optional[str] = None
     """
-    The URL to the Spark Master endpoint from, and only from the perspective of the JupyterLab Notebook. This is NOT the URL to use for accessing the cluster from a private server.
+    The URL that is used to reach the cluster from the notebook when available. This URL cannot be used to reach the cluster from a server.
     """
 
 
@@ -436,7 +436,7 @@ class CreateDatalabRequest:
 
     has_notebook: bool
     """
-    Whether a JupyterLab notebook shall be created with the Data Lab or not.
+    Select this option to include a notebook as part of the Data Lab.
     """
 
     spark_version: str
@@ -446,7 +446,7 @@ class CreateDatalabRequest:
 
     private_network_id: str
     """
-    The private network to which the Data Lab is connected. Important for accessing the Spark Master URL from a private cluster.
+    The unique identifier of the private network the Data Lab will be attached to.
     """
 
     region: Optional[ScwRegion] = None
@@ -466,17 +466,17 @@ class CreateDatalabRequest:
 
     main: Optional[CreateDatalabRequestSparkMain] = None
     """
-    The Spark main node configuration of the Data Lab, has one parameter `node_type` which specifies the compute node type of the main node. See ListNodeTypes for available options.
+    The cluster main node specification. It holds the parameters `node_type` which specifies the node type of the main node. See ListNodeTypes for available options. See ListNodeTypes for available options.
     """
 
     worker: Optional[CreateDatalabRequestSparkWorker] = None
     """
-    The Spark worker node configuration of the Data Lab, has two parameters `node_type` for selecting the type of the worker node, and `node_count` for specifying the amount of nodes.
+    The cluster worker node specification. It holds the parameters `node_type` which specifies the node type of the worker node and `node_count` for specifying the amount of nodes.
     """
 
     total_storage: Optional[Volume] = None
     """
-    The total storage selected by the user for Spark workers. This means the workers will not use more then this amount for their workload.
+    The maximum persistent volume storage that will be available during workload.
     """
 
 
@@ -563,7 +563,7 @@ class ListClusterVersionsResponse:
 @dataclass
 class ListDatalabsRequest:
     """
-    A request to list Datalabs.
+    A request to list Data Labs.
     """
 
     region: Optional[ScwRegion] = None
@@ -620,7 +620,7 @@ class ListDatalabsResponse:
 
     total_count: int
     """
-    The total count of Datalabs.
+    The total count of Data Labs.
     """
 
 
@@ -654,7 +654,7 @@ class ListNodeTypesRequest:
 
     targets: Optional[list[NodeTypeTarget]] = field(default_factory=list)
     """
-    Filter on the wanted targets, whether it's for main node or worker.
+    Filter based on the target of the nodes. Allows to filter the nodes based on their purpose which can be main or worker node.
     """
 
     resource_type: Optional[ListNodeTypesRequestResourceType] = (

scaleway/scaleway/datalab/v1beta1/api.py

@@ -72,15 +72,15 @@ def create_datalab(
         Create a new Data Lab. In this call, one can personalize the node counts, add a notebook, choose the private network, define the persistent volume storage capacity.
         :param name: The name of the Data Lab.
         :param description: The description of the Data Lab.
-        :param has_notebook: Whether a JupyterLab notebook shall be created with the Data Lab or not.
+        :param has_notebook: Select this option to include a notebook as part of the Data Lab.
         :param spark_version: The version of Spark running inside the Data Lab, available options can be viewed at ListClusterVersions.
-        :param private_network_id: The private network to which the Data Lab is connected. Important for accessing the Spark Master URL from a private cluster.
+        :param private_network_id: The unique identifier of the private network the Data Lab will be attached to.
         :param region: Region to target. If none is passed will use default region from the config.
         :param project_id: The unique identifier of the project where the Data Lab will be created.
         :param tags: The tags of the Data Lab.
-        :param main: The Spark main node configuration of the Data Lab, has one parameter `node_type` which specifies the compute node type of the main node. See ListNodeTypes for available options.
-        :param worker: The Spark worker node configuration of the Data Lab, has two parameters `node_type` for selecting the type of the worker node, and `node_count` for specifying the amount of nodes.
-        :param total_storage: The total storage selected by the user for Spark workers. This means the workers will not use more then this amount for their workload.
+        :param main: The cluster main node specification. It holds the parameters `node_type` which specifies the node type of the main node. See ListNodeTypes for available options. See ListNodeTypes for available options.
+        :param worker: The cluster worker node specification. It holds the parameters `node_type` which specifies the node type of the worker node and `node_count` for specifying the amount of nodes.
+        :param total_storage: The maximum persistent volume storage that will be available during workload.
         :return: :class:`Datalab <Datalab>`
 
         Usage:
@@ -386,12 +386,12 @@ def list_node_types(
         resource_type: Optional[ListNodeTypesRequestResourceType] = None,
     ) -> ListNodeTypesResponse:
         """
-        List the available compute node types upon which a Data Lab can be created.
+        List the available compute node types for creating a Data Lab.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
         :param order_by: The order by field. Available fields are `name_asc`, `name_desc`, `vcpus_asc`, `vcpus_desc`, `memory_gigabytes_asc`, `memory_gigabytes_desc`, `vram_bytes_asc`, `vram_bytes_desc`, `gpus_asc`, `gpus_desc`.
-        :param targets: Filter on the wanted targets, whether it's for main node or worker.
+        :param targets: Filter based on the target of the nodes. Allows to filter the nodes based on their purpose which can be main or worker node.
         :param resource_type: Filter based on node type ( `cpu`/`gpu`/`all` ).
         :return: :class:`ListNodeTypesResponse <ListNodeTypesResponse>`
 
@@ -431,12 +431,12 @@ def list_node_types_all(
         resource_type: Optional[ListNodeTypesRequestResourceType] = None,
     ) -> list[NodeType]:
         """
-        List the available compute node types upon which a Data Lab can be created.
+        List the available compute node types for creating a Data Lab.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
         :param order_by: The order by field. Available fields are `name_asc`, `name_desc`, `vcpus_asc`, `vcpus_desc`, `memory_gigabytes_asc`, `memory_gigabytes_desc`, `vram_bytes_asc`, `vram_bytes_desc`, `gpus_asc`, `gpus_desc`.
-        :param targets: Filter on the wanted targets, whether it's for main node or worker.
+        :param targets: Filter based on the target of the nodes. Allows to filter the nodes based on their purpose which can be main or worker node.
         :param resource_type: Filter based on node type ( `cpu`/`gpu`/`all` ).
         :return: :class:`list[NodeType] <list[NodeType]>`
 
@@ -469,7 +469,7 @@ def list_notebook_versions(
         order_by: Optional[ListNotebookVersionsRequestOrderBy] = None,
     ) -> ListNotebookVersionsResponse:
         """
-        List available notebook versions.
+        Lists available notebook versions.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.
@@ -508,7 +508,7 @@ def list_notebook_versions_all(
         order_by: Optional[ListNotebookVersionsRequestOrderBy] = None,
     ) -> list[Notebook]:
         """
-        List available notebook versions.
+        Lists available notebook versions.
         :param region: Region to target. If none is passed will use default region from the config.
         :param page: The page number.
         :param page_size: The page size.