[ml] Update compute reference documentation (Azure#31774)

* Update docstring for AmlCompute

* Update load_compute docstring and add example

* Update compute operations docstrings and add examples

* Update amlcompute docstrings and add examples

* Update compute instance docstrings and add examples

* Update vm compute docstrings and add examples

* Update aml compute node info docstrings

* Update compute docstrings and add example

* Update compute configuration docstring

* Update schedule and compute runtime docstrings and add examples

* Update unsupported compute docstring

* Update image metadata docstring and add example

* Update kubernetes compute docstring and add example

* Update materialization compute resource docstring and add example

* Update VmSize docstring

* Update compute samples

* Update sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py

Co-authored-by: kdestin <101366538+kdestin@users.noreply.github.com>

---------

Co-authored-by: kdestin <101366538+kdestin@users.noreply.github.com>

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_aml_compute_node_info.py

@@ -10,10 +10,9 @@
 
 
 class AmlComputeNodeInfo:
-    def __init__(self):
-        """Compute node information related to a AmlCompute Variables are only populated by the server, and will be
-        ignored when sending a request."""
+    """Compute node information related to AmlCompute."""
 
+    def __init__(self):
         self.node_id = None
         self.private_ip_address = None
         self.port = None
@@ -22,10 +21,20 @@ def __init__(self):
 
     @property
     def current_job_name(self) -> str:
+        """The run ID of the current job.
+
+        :return: The run ID of the current job.
+        :rtype: str
+        """
         return self.run_id
 
     @current_job_name.setter
     def current_job_name(self, value: str) -> None:
+        """Set the current job run ID.
+
+        :param value: The job run ID.
+        :type value: str
+        """
         self.run_id = value
 
     @classmethod

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py

@@ -4,36 +4,55 @@
 
 
 class ImageMetadata:
-    """Metadata about the operating system image for this compute instance."""
-
-    def __init__(self, *, is_latest_os_image_version: bool, current_image_version: str, latest_image_version: str):
+    """Metadata about the operating system image for the compute instance.
+
+    :param is_latest_os_image_version: Specifies if the compute instance is running on the latest OS image version.
+    :type is_latest_os_image_version: bool
+    :param current_image_version: Version of the current image.
+    :type current_image_version: str
+    :param latest_image_version: The latest image version.
+    :type latest_image_version: str
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+            :start-after: [START image_metadata]
+            :end-before: [END image_metadata]
+            :language: python
+            :dedent: 8
+            :caption: Creating a ImageMetadata object.
+    """
+
+    def __init__(
+        self, *, is_latest_os_image_version: bool, current_image_version: str, latest_image_version: str
+    ) -> None:
         self._is_latest_os_image_version = is_latest_os_image_version
         self._current_image_version = current_image_version
         self._latest_image_version = latest_image_version
 
     @property
     def is_latest_os_image_version(self) -> bool:
-        """Indicates whether a compute instance is running on the latest OS image version.
+        """Whether or not a compute instance is running on the latest OS image version.
 
-        :return: State of whether the compute instance is running the latest OS image version.
+        :return: Boolean indicating if the compute instance is running the latest OS image version.
         :rtype: bool
         """
         return self._is_latest_os_image_version
 
     @property
     def current_image_version(self) -> str:
-        """Indicates the current OS image version number.
+        """The current OS image version number.
 
-        :return: Current OS Image version number.
+        :return: The current OS image version number.
         :rtype: str
         """
         return self._current_image_version
 
     @property
     def latest_image_version(self) -> str:
-        """Indicates the latest OS image version number.
+        """The latest OS image version number.
 
-        :return: Latest OS Image version number.
+        :return: The latest OS image version number.
         :rtype: str
         """
         return self._latest_image_version

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py

@@ -18,13 +18,22 @@ class ComputeStartStopSchedule(RestTranslatableMixin):
     """Schedules for compute start or stop scenario.
 
     :param trigger: The trigger of the schedule.
-    :type trigger: Trigger
+    :type trigger: Union[~azure.ai.ml.entities.CronTrigger, ~azure.ai.ml.entities.RecurrenceTrigger]
     :param action: The compute power action.
-    :type action: ComputePowerAction
+    :type action: ~azure.ai.ml.entities.ComputePowerAction
     :param state: The state of the schedule.
-    :type state: ScheduleState
+    :type state: ~azure.ai.ml.entities.ScheduleState
     :param kwargs: A dictionary of additional configuration parameters.
     :type kwargs: dict
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+            :start-after: [START compute_start_stop_schedule]
+            :end-before: [END compute_start_stop_schedule]
+            :language: python
+            :dedent: 8
+            :caption: Creating a ComputeStartStopSchedule object.
     """
 
     def __init__(
@@ -34,7 +43,7 @@ def __init__(
         action: Optional[ComputePowerAction] = None,
         state: ScheduleState = ScheduleState.ENABLED,
         **kwargs
-    ):
+    ) -> None:
         self.trigger = trigger
         self.action = action
         self.state = state
@@ -43,18 +52,18 @@ def __init__(
 
     @property
     def schedule_id(self) -> Optional[str]:
-        """Schedule id, readonly.
+        """The schedule ID.
 
-        :return: Schedule id.
+        :return: The schedule ID.
         :rtype: Optional[str]
         """
         return self._schedule_id
 
     @property
     def provisioning_state(self) -> Optional[str]:
-        """Schedule provisioning state, readonly.
+        """The schedule provisioning state.
 
-        :return: Schedule provisioning state.
+        :return: The schedule provisioning state.
         :rtype: Optional[str]
         """
         return self._provisioning_state
@@ -105,12 +114,21 @@ class ComputeSchedules(RestTranslatableMixin):
     """Compute schedules.
 
     :param compute_start_stop: Compute start or stop schedules.
-    :type compute_start_stop: List[ComputeStartStopSchedule]
+    :type compute_start_stop: List[~azure.ai.ml.entities.ComputeStartStopSchedule]
     :param kwargs: A dictionary of additional configuration parameters.
     :type kwargs: dict
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+            :start-after: [START compute_start_stop_schedule]
+            :end-before: [END compute_start_stop_schedule]
+            :language: python
+            :dedent: 8
+            :caption: Creating a ComputeSchedules object.
     """
 
-    def __init__(self, *, compute_start_stop: Optional[List[ComputeStartStopSchedule]] = None):
+    def __init__(self, *, compute_start_stop: Optional[List[ComputeStartStopSchedule]] = None) -> None:
         self.compute_start_stop = compute_start_stop
 
     def _to_rest_object(self) -> RestComputeSchedules:

sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_vm_size.py

@@ -13,7 +13,33 @@
 
 
 class VmSize(RestTranslatableMixin):
-    """virtual Machine Size."""
+    """Virtual Machine Size.
+
+    :param name: The virtual machine size name.
+    :type name: Optional[str]
+    :param family: The virtual machine size family name.
+    :type family: Optional[str]
+    :param v_cp_us: The number of vCPUs supported by the virtual machine size.
+    :type v_cp_us: Optional[int]
+    :param gpus: The number of GPUs supported by the virtual machine size.
+    :type gpus: Optional[int]
+    :param os_vhd_size_mb: The OS VHD disk size, in MB, allowed by the virtual machine size.
+    :type os_vhd_size_mb: Optional[int]
+    :param max_resource_volume_mb: The resource volume size, in MB, allowed by the virtual machine
+        size.
+    :type max_resource_volume_mb: Optional[int]
+    :param memory_gb: The amount of memory, in GB, supported by the virtual machine size.
+    :type memory_gb: Optional[float]
+    :param low_priority_capable: Specifies if the virtual machine size supports low priority VMs.
+    :type low_priority_capable: Optional[bool]
+    :param premium_io: Specifies if the virtual machine size supports premium IO.
+    :type premium_io: Optional[bool]
+    :param estimated_vm_prices: The estimated price information for using a VM.
+    :type estimated_vm_prices: ~azure.mgmt.machinelearningservices.models.EstimatedVMPrices
+    :param supported_compute_types: Specifies the compute types supported by the virtual machine
+        size.
+    :type supported_compute_types: Optional[list[str]]
+    """
 
     def __init__(
         self,
@@ -27,35 +53,7 @@ def __init__(
         low_priority_capable: Optional[bool] = None,
         premium_io: Optional[bool] = None,
         supported_compute_types: Optional[List[str]] = None,
-    ):
-        """Virtual machine size.
-
-        :param name: The name of the virtual machine size.
-        :type name: str
-        :param family: The family name of the virtual machine size.
-        :type family: str
-        :param v_cp_us: The number of vCPUs supported by the virtual machine size.
-        :type v_cp_us: int
-        :param gpus: The number of gPUs supported by the virtual machine size.
-        :type gpus: int
-        :param os_vhd_size_mb: The OS VHD disk size, in MB, allowed by the virtual machine size.
-        :type os_vhd_size_mb: int
-        :param max_resource_volume_mb: The resource volume size, in MB, allowed by the virtual machine
-        size.
-        :type max_resource_volume_mb: int
-        :param memory_gb: The amount of memory, in GB, supported by the virtual machine size.
-        :type memory_gb: float
-        :param low_priority_capable: Specifies if the virtual machine size supports low priority VMs.
-        :type low_priority_capable: bool
-        :param premium_io: Specifies if the virtual machine size supports premium IO.
-        :type premium_io: bool
-        :param estimated_vm_prices: The estimated price information for using a VM.
-        :type estimated_vm_prices: ~azure.mgmt.machinelearningservices.models.EstimatedVMPrices
-        :param supported_compute_types: Specifies the compute types supported by the virtual machine
-        size.
-        :type supported_compute_types: list[str]
-        """
-
+    ) -> None:
         self.name = name
         self.family = family
         self.v_cp_us = v_cp_us