docs: fix minor docstring formatting (#72)

gcf-owl-bot[bot] · web-flow · commit 9414457a16f8 · 2022-11-21T15:36:45.000-05:00
* feat: Adds named reservation to InstancePolicy --- docs:Remove "not yet implemented" for Accelerator & Refine Volume API docs --- docs: update the job id format requirement PiperOrigin-RevId: 489501779 Source-Link: googleapis/googleapis@488a4bd Source-Link: https://github.com/googleapis/googleapis-gen/commit/5b3d3a550015e9367ad13ee5f9febe0c3f84cf33 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNWIzZDNhNTUwMDE1ZTkzNjdhZDEzZWU1ZjlmZWJlMGMzZjg0Y2YzMyJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * feat: Adds named reservation to InstancePolicy --- docs:Remove "not yet implemented" for Accelerator & Refine Volume API docs --- docs: update the job id format requirement PiperOrigin-RevId: 489502315 Source-Link: googleapis/googleapis@db1cc11 Source-Link: https://github.com/googleapis/googleapis-gen/commit/fcc564ef064c7dff31d7970e12318ad084703ac6 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZmNjNTY0ZWYwNjRjN2RmZjMxZDc5NzBlMTIzMThhZDA4NDcwM2FjNiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * docs: fix minor docstring formatting PiperOrigin-RevId: 490003354 Source-Link: googleapis/googleapis@9afb89b Source-Link: https://github.com/googleapis/googleapis-gen/commit/c51774cd8dd5804d5ec6f335b1855c28d1171a56 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiYzUxNzc0Y2Q4ZGQ1ODA0ZDVlYzZmMzM1YjE4NTVjMjhkMTE3MWE1NiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
diff --git a/google/cloud/batch_v1/services/batch_service/async_client.py b/google/cloud/batch_v1/services/batch_service/async_client.py
@@ -285,11 +285,11 @@ async def sample_create_job():
                 should not be set.
             job_id (:class:`str`):
                 ID used to uniquely identify the Job within its parent
-                scope. This field should contain at most 63 characters.
-                Only alphanumeric characters or '-' are accepted. The
-                '-' character cannot be the first or the last one. A
-                system generated ID will be used if the field is not
-                set.
+                scope. This field should contain at most 63 characters
+                and must start with lowercase characters. Only lowercase
+                characters, numbers and '-' are accepted. The '-'
+                character cannot be the first or the last one. A system
+                generated ID will be used if the field is not set.
 
                 The job.name field in the request will be ignored and
                 the created resource name of the Job will be
diff --git a/google/cloud/batch_v1/services/batch_service/client.py b/google/cloud/batch_v1/services/batch_service/client.py
@@ -565,11 +565,11 @@ def sample_create_job():
                 should not be set.
             job_id (str):
                 ID used to uniquely identify the Job within its parent
-                scope. This field should contain at most 63 characters.
-                Only alphanumeric characters or '-' are accepted. The
-                '-' character cannot be the first or the last one. A
-                system generated ID will be used if the field is not
-                set.
+                scope. This field should contain at most 63 characters
+                and must start with lowercase characters. Only lowercase
+                characters, numbers and '-' are accepted. The '-'
+                character cannot be the first or the last one. A system
+                generated ID will be used if the field is not set.
 
                 The job.name field in the request will be ignored and
                 the created resource name of the Job will be
diff --git a/google/cloud/batch_v1/types/batch.py b/google/cloud/batch_v1/types/batch.py
@@ -47,10 +47,11 @@ class CreateJobRequest(proto.Message):
             "projects/{project}/locations/{location}".
         job_id (str):
             ID used to uniquely identify the Job within its parent
-            scope. This field should contain at most 63 characters. Only
-            alphanumeric characters or '-' are accepted. The '-'
-            character cannot be the first or the last one. A system
-            generated ID will be used if the field is not set.
+            scope. This field should contain at most 63 characters and
+            must start with lowercase characters. Only lowercase
+            characters, numbers and '-' are accepted. The '-' character
+            cannot be the first or the last one. A system generated ID
+            will be used if the field is not set.
 
             The job.name field in the request will be ignored and the
             created resource name of the Job will be
diff --git a/google/cloud/batch_v1/types/job.py b/google/cloud/batch_v1/types/job.py
@@ -445,8 +445,8 @@ class Disk(proto.Message):
         )
 
     class AttachedDisk(proto.Message):
-        r"""A new or an existing persistent disk or a local ssd attached
-        to a VM instance.
+        r"""A new or an existing persistent disk (PD) or a local ssd
+        attached to a VM instance.
 
         This message has `oneof`_ fields (mutually exclusive fields).
         For each oneof, at most one member field can be set at the same time.
@@ -488,7 +488,7 @@ class AttachedDisk(proto.Message):
 
     class Accelerator(proto.Message):
         r"""Accelerator describes Compute Engine accelerators to be
-        attached to VMs.
+        attached to the VM.
 
         Attributes:
             type_ (str):
@@ -529,11 +529,11 @@ class InstancePolicy(proto.Message):
                 The provisioning model.
             accelerators (MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.Accelerator]):
                 The accelerators attached to each VM
-                instance. Not yet implemented.
+                instance.
             disks (MutableSequence[google.cloud.batch_v1.types.AllocationPolicy.AttachedDisk]):
                 Non-boot disks to be attached for each VM
                 created by this InstancePolicy. New disks will
-                be deleted when the attached VM is deleted.
+                be deleted when the VM is deleted.
         """
 
         machine_type: str = proto.Field(
diff --git a/google/cloud/batch_v1/types/volume.py b/google/cloud/batch_v1/types/volume.py
@@ -28,9 +28,8 @@
 
 
 class Volume(proto.Message):
-    r"""Volume and mount parameters to be associated with a TaskSpec.
-    A TaskSpec might describe zero, one, or multiple volumes to be
-    mounted as part of the task.
+    r"""Volume describes a volume and parameters for it to be mounted
+    to a VM.
 
     This message has `oneof`_ fields (mutually exclusive fields).
     For each oneof, at most one member field can be set at the same time.
@@ -41,28 +40,39 @@ class Volume(proto.Message):
 
     Attributes:
         nfs (google.cloud.batch_v1.types.NFS):
-            An NFS source for the volume (could be a
-            Filestore, for example).
+            A Network File System (NFS) volume. For
+            example, a Filestore file share.
 
             This field is a member of `oneof`_ ``source``.
         gcs (google.cloud.batch_v1.types.GCS):
-            A Google Cloud Storage source for the volume.
+            A Google Cloud Storage (GCS) volume.
 
             This field is a member of `oneof`_ ``source``.
         device_name (str):
-            Device name of an attached disk
+            Device name of an attached disk volume, which should align
+            with a device_name specified by
+            job.allocation_policy.instances[0].policy.disks[i].device_name
+            or defined by the given instance template in
+            job.allocation_policy.instances[0].instance_template.
 
             This field is a member of `oneof`_ ``source``.
         mount_path (str):
-            Mount path for the volume, e.g. /mnt/share
+            The mount path for the volume, e.g.
+            /mnt/disks/share.
         mount_options (MutableSequence[str]):
-            Mount options For Google Cloud Storage, mount options are
-            the global options supported by gcsfuse tool. Batch will use
-            them to mount the volume with the following command:
-            "gcsfuse [global options] bucket mountpoint". For PD, NFS,
-            mount options are these supported by /etc/fstab. Batch will
-            use Fstab to mount such volumes.
-            https://help.ubuntu.com/community/Fstab
+            For Google Cloud Storage (GCS), mount options
+            are the options supported by the gcsfuse tool
+            (https://github.com/GoogleCloudPlatform/gcsfuse).
+            For existing persistent disks, mount options
+            provided by the mount command
+            (https://man7.org/linux/man-pages/man8/mount.8.html)
+            except writing are supported. This is due to
+            restrictions of multi-writer mode
+            (https://cloud.google.com/compute/docs/disks/sharing-disks-between-vms).
+            For other attached disks and Network File System
+            (NFS), mount options are these supported by the
+            mount command
+            (https://man7.org/linux/man-pages/man8/mount.8.html).
     """
 
     nfs: "NFS" = proto.Field(
@@ -93,14 +103,14 @@ class Volume(proto.Message):
 
 
 class NFS(proto.Message):
-    r"""Represents an NFS server and remote path: :<remote_path>
+    r"""Represents an NFS volume.
 
     Attributes:
         server (str):
-            URI of the NFS server, e.g. an IP address.
+            The IP address of the NFS.
         remote_path (str):
-            Remote source path exported from NFS, e.g.,
-            "/share".
+            Remote source path exported from the NFS,
+            e.g., "/share".
     """
 
     server: str = proto.Field(
@@ -114,7 +124,7 @@ class NFS(proto.Message):
 
 
 class GCS(proto.Message):
-    r"""Represents a Google Cloud Storage volume source config.
+    r"""Represents a Google Cloud Storage volume.
 
     Attributes:
         remote_path (str):
diff --git a/google/cloud/batch_v1alpha/services/batch_service/async_client.py b/google/cloud/batch_v1alpha/services/batch_service/async_client.py
@@ -285,11 +285,11 @@ async def sample_create_job():
                 should not be set.
             job_id (:class:`str`):
                 ID used to uniquely identify the Job within its parent
-                scope. This field should contain at most 63 characters.
-                Only alphanumeric characters or '-' are accepted. The
-                '-' character cannot be the first or the last one. A
-                system generated ID will be used if the field is not
-                set.
+                scope. This field should contain at most 63 characters
+                and must start with lowercase characters. Only lowercase
+                characters, numbers and '-' are accepted. The '-'
+                character cannot be the first or the last one. A system
+                generated ID will be used if the field is not set.
 
                 The job.name field in the request will be ignored and
                 the created resource name of the Job will be
diff --git a/google/cloud/batch_v1alpha/services/batch_service/client.py b/google/cloud/batch_v1alpha/services/batch_service/client.py
@@ -565,11 +565,11 @@ def sample_create_job():
                 should not be set.
             job_id (str):
                 ID used to uniquely identify the Job within its parent
-                scope. This field should contain at most 63 characters.
-                Only alphanumeric characters or '-' are accepted. The
-                '-' character cannot be the first or the last one. A
-                system generated ID will be used if the field is not
-                set.
+                scope. This field should contain at most 63 characters
+                and must start with lowercase characters. Only lowercase
+                characters, numbers and '-' are accepted. The '-'
+                character cannot be the first or the last one. A system
+                generated ID will be used if the field is not set.
 
                 The job.name field in the request will be ignored and
                 the created resource name of the Job will be
diff --git a/google/cloud/batch_v1alpha/types/batch.py b/google/cloud/batch_v1alpha/types/batch.py
@@ -47,10 +47,11 @@ class CreateJobRequest(proto.Message):
             "projects/{project}/locations/{location}".
         job_id (str):
             ID used to uniquely identify the Job within its parent
-            scope. This field should contain at most 63 characters. Only
-            alphanumeric characters or '-' are accepted. The '-'
-            character cannot be the first or the last one. A system
-            generated ID will be used if the field is not set.
+            scope. This field should contain at most 63 characters and
+            must start with lowercase characters. Only lowercase
+            characters, numbers and '-' are accepted. The '-' character
+            cannot be the first or the last one. A system generated ID
+            will be used if the field is not set.
 
             The job.name field in the request will be ignored and the
             created resource name of the Job will be
diff --git a/google/cloud/batch_v1alpha/types/job.py b/google/cloud/batch_v1alpha/types/job.py
@@ -408,7 +408,7 @@ class AllocationPolicy(proto.Message):
             Deprecated: please use instances[0].template instead.
         provisioning_models (MutableSequence[google.cloud.batch_v1alpha.types.AllocationPolicy.ProvisioningModel]):
             Deprecated: please use
-            instances[i].policy.provisioning_model instead.
+            instances[0].policy.provisioning_model instead.
         service_account_email (str):
             Deprecated: please use service_account instead.
         service_account (google.cloud.batch_v1alpha.types.ServiceAccount):
@@ -525,8 +525,8 @@ class Disk(proto.Message):
         )
 
     class AttachedDisk(proto.Message):
-        r"""A new or an existing persistent disk or a local ssd attached
-        to a VM instance.
+        r"""A new or an existing persistent disk (PD) or a local ssd
+        attached to a VM instance.
 
         This message has `oneof`_ fields (mutually exclusive fields).
         For each oneof, at most one member field can be set at the same time.
@@ -568,7 +568,7 @@ class AttachedDisk(proto.Message):
 
     class Accelerator(proto.Message):
         r"""Accelerator describes Compute Engine accelerators to be
-        attached to VMs.
+        attached to the VM.
 
         Attributes:
             type_ (str):
@@ -611,11 +611,14 @@ class InstancePolicy(proto.Message):
                 The provisioning model.
             accelerators (MutableSequence[google.cloud.batch_v1alpha.types.AllocationPolicy.Accelerator]):
                 The accelerators attached to each VM
-                instance. Not yet implemented.
+                instance.
             disks (MutableSequence[google.cloud.batch_v1alpha.types.AllocationPolicy.AttachedDisk]):
                 Non-boot disks to be attached for each VM
                 created by this InstancePolicy. New disks will
-                be deleted when the attached VM is deleted.
+                be deleted when the VM is deleted.
+            reservation (str):
+                If specified, VMs will be allocated only
+                inside the matching reservation.
         """
 
         allowed_machine_types: MutableSequence[str] = proto.RepeatedField(
@@ -647,6 +650,10 @@ class InstancePolicy(proto.Message):
             number=6,
             message="AllocationPolicy.AttachedDisk",
         )
+        reservation: str = proto.Field(
+            proto.STRING,
+            number=7,
+        )
 
     class InstancePolicyOrTemplate(proto.Message):
         r"""Either an InstancePolicy or an instance template.
diff --git a/google/cloud/batch_v1alpha/types/volume.py b/google/cloud/batch_v1alpha/types/volume.py
@@ -29,9 +29,8 @@
 
 
 class Volume(proto.Message):
-    r"""Volume and mount parameters to be associated with a TaskSpec.
-    A TaskSpec might describe zero, one, or multiple volumes to be
-    mounted as part of the task.
+    r"""Volume describes a volume and parameters for it to be mounted
+    to a VM.
 
     This message has `oneof`_ fields (mutually exclusive fields).
     For each oneof, at most one member field can be set at the same time.
@@ -42,32 +41,43 @@ class Volume(proto.Message):
 
     Attributes:
         nfs (google.cloud.batch_v1alpha.types.NFS):
-            An NFS source for the volume (could be a
-            Filestore, for example).
+            A Network File System (NFS) volume. For
+            example, a Filestore file share.
 
             This field is a member of `oneof`_ ``source``.
         pd (google.cloud.batch_v1alpha.types.PD):
-            A persistent disk source for the volume.
+            Deprecated: please use device_name instead.
 
             This field is a member of `oneof`_ ``source``.
         gcs (google.cloud.batch_v1alpha.types.GCS):
-            A Google Cloud Storage source for the volume.
+            A Google Cloud Storage (GCS) volume.
 
             This field is a member of `oneof`_ ``source``.
         device_name (str):
-            Device name of an attached disk
+            Device name of an attached disk volume, which should align
+            with a device_name specified by
+            job.allocation_policy.instances[0].policy.disks[i].device_name
+            or defined by the given instance template in
+            job.allocation_policy.instances[0].instance_template.
 
             This field is a member of `oneof`_ ``source``.
         mount_path (str):
-            Mount path for the volume, e.g. /mnt/share
+            The mount path for the volume, e.g.
+            /mnt/disks/share.
         mount_options (MutableSequence[str]):
-            Mount options For Google Cloud Storage, mount options are
-            the global options supported by gcsfuse tool. Batch will use
-            them to mount the volume with the following command:
-            "gcsfuse [global options] bucket mountpoint". For PD, NFS,
-            mount options are these supported by /etc/fstab. Batch will
-            use Fstab to mount such volumes.
-            https://help.ubuntu.com/community/Fstab
+            For Google Cloud Storage (GCS), mount options
+            are the options supported by the gcsfuse tool
+            (https://github.com/GoogleCloudPlatform/gcsfuse).
+            For existing persistent disks, mount options
+            provided by the mount command
+            (https://man7.org/linux/man-pages/man8/mount.8.html)
+            except writing are supported. This is due to
+            restrictions of multi-writer mode
+            (https://cloud.google.com/compute/docs/disks/sharing-disks-between-vms).
+            For other attached disks and Network File System
+            (NFS), mount options are these supported by the
+            mount command
+            (https://man7.org/linux/man-pages/man8/mount.8.html).
     """
 
     nfs: "NFS" = proto.Field(
@@ -104,14 +114,14 @@ class Volume(proto.Message):
 
 
 class NFS(proto.Message):
-    r"""Represents an NFS server and remote path: :<remote_path>
+    r"""Represents an NFS volume.
 
     Attributes:
         server (str):
-            URI of the NFS server, e.g. an IP address.
+            The IP address of the NFS.
         remote_path (str):
-            Remote source path exported from NFS, e.g.,
-            "/share".
+            Remote source path exported from the NFS,
+            e.g., "/share".
     """
 
     server: str = proto.Field(
@@ -125,7 +135,7 @@ class NFS(proto.Message):
 
 
 class PD(proto.Message):
-    r"""Represents a GCP persistent disk
+    r"""Deprecated: please use device_name instead.
 
     Attributes:
         disk (str):
@@ -155,7 +165,7 @@ class PD(proto.Message):
 
 
 class GCS(proto.Message):
-    r"""Represents a Google Cloud Storage volume source config.
+    r"""Represents a Google Cloud Storage volume.
 
     Attributes:
         remote_path (str):
diff --git a/tests/unit/gapic/batch_v1alpha/test_batch_service.py b/tests/unit/gapic/batch_v1alpha/test_batch_service.py
