[ml] Fix Sphinx docstring rendering errors (Azure#32069)

* Add line between directive and content * Fix literalinclude for ml_client * Remove non-existent example references * Add blank line for formatting * Fix bullet list * Leave spaces after admonitions * Fix remarks section * Fix indentation/formatting * Fix indentation/formatting * Change MLClient note to example * Update README with path instructions * Fix relative paths in samples admonitions * Fix indentation * Remove en-us locale tag from link * Correct README * Fix paths * Consolidate type to parent class for brevity and syntax
whisper6284 · Sep 20, 2023 · 2d22fc9 · 2d22fc9
1 parent 547f95e
commit 2d22fc9
Show file tree

Hide file tree

Showing 78 changed files with 319 additions and 782 deletions.
diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/_ml_client.py b/sdk/ml/azure-ai-ml/azure/ai/ml/_ml_client.py
@@ -129,17 +129,15 @@ class MLClient:
             :dedent: 8
             :caption: Creating the MLClient with Azure Identity credentials.
 
-    .. note:: Additional Note
-
-       When using sovereign domains (i.e. any cloud other than AZURE_PUBLIC_CLOUD), you must pass in the cloud name in
-       kwargs and you must use an authority with DefaultAzureCredential.
+    .. admonition:: Example:
 
        .. literalinclude:: ../samples/ml_samples_authentication.py
             :start-after: [START create_ml_client_sovereign_cloud]
             :end-before: [END create_ml_client_sovereign_cloud]
             :language: python
             :dedent: 8
-            :caption: Creating the MLClient with Azure Identity credentials and a sovereign cloud.
+            :caption: When using sovereign domains (i.e. any cloud other than AZURE_PUBLIC_CLOUD), you must pass in the
+                cloud name in kwargs and you must use an authority with DefaultAzureCredential.
     """
 
     # pylint: disable=client-method-missing-type-annotations
@@ -601,6 +599,7 @@ def from_config(
         format:
 
         .. code-block:: json
+
             {
                 "subscription_id": "<subscription-id>",
                 "resource_group": "<resource-group>",
@@ -634,15 +633,13 @@ def from_config(
                 :dedent: 8
                 :caption: Creating an MLClient from a file named "config.json" in directory "src".
 
-        .. admonition:: Example:
-
             .. literalinclude:: ../samples/ml_samples_authentication.py
                 :start-after: [START create_ml_client_from_config_custom_filename]
                 :end-before: [END create_ml_client_from_config_custom_filename]
                 :language: python
                 :dedent: 8
                 :caption: Creating an MLClient from a file named "team_workspace_configuration.json" in the current
-                directory.
+                    directory.
         """
 
         path = Path(".") if path is None else Path(path)
@@ -1016,15 +1013,6 @@ def create_or_update(
         :return: The created or updated resource.
         :rtype: typing.Union[~azure.ai.ml.entities.Job, ~azure.ai.ml.entities.Model
             , ~azure.ai.ml.entities.Environment, ~azure.ai.ml.entities.Component, ~azure.ai.ml.entities.Datastore]
-
-        .. admonition:: Example:
-
-            .. literalinclude:: ../samples/ml_samples_misc.py
-                :start-after: [START ml_client_create_or_update]
-                :end-before: [END ml_client_create_or_update]
-                :language: python
-                :dedent: 8
-                :caption: Creating a resource asynchronously via MLClient.
         """
 
         return _create_or_update(entity, self._operation_container.all_operations, **kwargs)
@@ -1061,15 +1049,6 @@ def begin_create_or_update(
             , ~azure.ai.ml.entities.Registry, ~azure.ai.ml.entities.Compute, ~azure.ai.ml.entities.OnlineDeployment
             , ~azure.ai.ml.entities.OnlineEndpoint, ~azure.ai.ml.entities.BatchDeployment
             , ~azure.ai.ml.entities.BatchEndpoint, ~azure.ai.ml.entities.Schedule]]
-
-        .. admonition:: Example:
-
-            .. literalinclude:: ../samples/ml_samples_misc.py
-                :start-after: [START ml_client_begin_create_or_update]
-                :end-before: [END ml_client_begin_create_or_update]
-                :language: python
-                :dedent: 8
-                :caption: Creating a resource asynchronously via MLClient.
         """
 
         return _begin_create_or_update(entity, self._operation_container.all_operations, **kwargs)

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/dsl/_pipeline_decorator.py b/sdk/ml/azure-ai-ml/azure/ai/ml/dsl/_pipeline_decorator.py
@@ -126,7 +126,7 @@ def pipeline(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../samples/ml_samples_pipeline_job_configurations.py
+        .. literalinclude:: ../samples/ml_samples_pipeline_job_configurations.py
             :start-after: [START configure_pipeline]
             :end-before: [END configure_pipeline]
             :language: python

diff --git a/...l/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/base_environment_source.py b/...l/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/base_environment_source.py
@@ -25,7 +25,7 @@ class BaseEnvironment:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START base_env_entity_create]
             :end-before: [END base_env_entity_create]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/model_configuration.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/model_configuration.py
@@ -19,7 +19,7 @@ class ModelConfiguration:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START model_configuration_entity_create]
             :end-before: [END model_configuration_entity_create]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/model_package.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/_package/model_package.py
@@ -8,31 +8,22 @@
 from pathlib import Path
 from typing import IO, AnyStr, Dict, List, Optional, Union
 
-
-from azure.ai.ml._restclient.v2023_02_01_preview.models import (
-    PackageRequest,
-    PackageResponse,
-    ModelPackageInput as RestModelPackageInput,
-    PackageInputPathId as RestPackageInputPathId,
-    PackageInputPathVersion as RestPackageInputPathVersion,
-    PackageInputPathUrl as RestPackageInputPathUrl,
-    CodeConfiguration,
-)
-from azure.ai.ml._restclient.v2021_10_01_dataplanepreview.models import (
-    PackageRequest as DataPlanePackageRequest,
-)
-from azure.ai.ml.entities._resource import Resource
+from azure.ai.ml._restclient.v2021_10_01_dataplanepreview.models import PackageRequest as DataPlanePackageRequest
+from azure.ai.ml._restclient.v2023_02_01_preview.models import CodeConfiguration
+from azure.ai.ml._restclient.v2023_02_01_preview.models import ModelPackageInput as RestModelPackageInput
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathId as RestPackageInputPathId
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathUrl as RestPackageInputPathUrl
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageInputPathVersion as RestPackageInputPathVersion
+from azure.ai.ml._restclient.v2023_02_01_preview.models import PackageRequest, PackageResponse
 from azure.ai.ml._schema.assets.package.model_package import ModelPackageSchema
 from azure.ai.ml._utils._experimental import experimental
 from azure.ai.ml._utils.utils import dump_yaml_to_file, snake_to_pascal
 from azure.ai.ml.constants._common import BASE_PATH_CONTEXT_KEY, PARAMS_OVERRIDE_KEY
+from azure.ai.ml.entities._resource import Resource
 from azure.ai.ml.entities._util import load_from_dict
 
 from .base_environment_source import BaseEnvironment
-from .inferencing_server import (
-    AzureMLBatchInferencingServer,
-    AzureMLOnlineInferencingServer,
-)
+from .inferencing_server import AzureMLBatchInferencingServer, AzureMLOnlineInferencingServer
 from .model_configuration import ModelConfiguration
 
 
@@ -156,7 +147,7 @@ class ModelPackageInput:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START model_package_input_entity_create]
             :end-before: [END model_package_input_entity_create]
             :language: python
@@ -219,7 +210,7 @@ class ModelPackage(Resource, PackageRequest):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START model_package_entity_create]
             :end-before: [END model_package_entity_create]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/model.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/_artifacts/model.py
@@ -60,7 +60,7 @@ class Model(Artifact):  # pylint: disable=too-many-instance-attributes
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START model_entity_create]
             :end-before: [END model_entity_create]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/environment.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/environment.py
@@ -40,7 +40,7 @@ class BuildContext:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START build_context_entity_create]
             :end-before: [END build_context_entity_create]
             :language: python
@@ -100,7 +100,7 @@ class Environment(Asset, LocalizableMixin):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START env_entity_create]
             :end-before: [END env_entity_create]
             :language: python
@@ -299,7 +299,7 @@ def validate(self):
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../../../../samples/ml_samples_misc.py
+            .. literalinclude:: ../samples/ml_samples_misc.py
                 :start-after: [START env_entities_validate]
                 :end-before: [END env_entities_validate]
                 :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/intellectual_property.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_assets/intellectual_property.py
@@ -22,7 +22,7 @@ class IntellectualProperty(RestTranslatableMixin):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_misc.py
+        .. literalinclude:: ../samples/ml_samples_misc.py
             :start-after: [START intellectual_property_configuration]
             :end-before: [END intellectual_property_configuration]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/command.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/command.py
@@ -480,7 +480,7 @@ def set_resources(
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../../../../samples/ml_samples_command_configurations.py
+            .. literalinclude:: ../samples/ml_samples_command_configurations.py
                 :start-after: [START command_set_resources]
                 :end-before: [END command_set_resources]
                 :language: python
@@ -515,7 +515,7 @@ def set_limits(self, *, timeout: int, **kwargs) -> None:  # pylint: disable=unus
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../../../../samples/ml_samples_command_configurations.py
+            .. literalinclude:: ../samples/ml_samples_command_configurations.py
                 :start-after: [START command_set_limits]
                 :end-before: [END command_set_limits]
                 :language: python
@@ -537,7 +537,7 @@ def set_queue_settings(self, *, job_tier: Optional[str] = None, priority: Option
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../../../../samples/ml_samples_command_configurations.py
+            .. literalinclude:: ../samples/ml_samples_command_configurations.py
                 :start-after: [START command_set_queue_settings]
                 :end-before: [END command_set_queue_settings]
                 :language: python
@@ -623,7 +623,7 @@ def sweep(
 
         .. admonition:: Example:
 
-            .. literalinclude:: ../../../../../samples/ml_samples_sweep_configurations.py
+            .. literalinclude:: ../samples/ml_samples_sweep_configurations.py
                 :start-after: [START configure_sweep_job_bandit_policy]
                 :end-before: [END configure_sweep_job_bandit_policy]
                 :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/command_func.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/command_func.py
@@ -221,7 +221,7 @@ def command(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_command_configurations.py
+        .. literalinclude:: ../samples/ml_samples_command_configurations.py
             :start-after: [START command_function]
             :end-before: [END command_function]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/spark_func.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_builders/spark_func.py
@@ -181,7 +181,7 @@ def spark(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_spark_configurations.py
+        .. literalinclude:: ../samples/ml_samples_spark_configurations.py
             :start-after: [START spark_function_configuration_1]
             :end-before: [END spark_function_configuration_1]
             :language: python
@@ -190,7 +190,7 @@ def spark(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_spark_configurations.py
+        .. literalinclude:: ../samples/ml_samples_spark_configurations.py
             :start-after: [START spark_function_configuration_2]
             :end-before: [END spark_function_configuration_2]
             :language: python
@@ -199,7 +199,7 @@ def spark(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_spark_configurations.py
+        .. literalinclude:: ../samples/ml_samples_spark_configurations.py
             :start-after: [START spark_dsl_pipeline]
             :end-before: [END spark_dsl_pipeline]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_component/command_component.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_component/command_component.py
@@ -84,7 +84,7 @@ class CommandComponent(Component, ParameterizedCommand, AdditionalIncludesMixin)
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_command_configurations.py
+        .. literalinclude:: ../samples/ml_samples_command_configurations.py
             :start-after: [START command_component_definition]
             :end-before: [END command_component_definition]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_component/spark_component.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_component/spark_component.py
@@ -82,7 +82,7 @@ class SparkComponent(
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_spark_configurations.py
+        .. literalinclude:: ../samples/ml_samples_spark_configurations.py
             :start-after: [START spark_component_definition]
             :end-before: [END spark_component_definition]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_image_metadata.py
@@ -15,7 +15,7 @@ class ImageMetadata:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+        .. literalinclude:: ../samples/ml_samples_compute.py
             :start-after: [START image_metadata]
             :end-before: [END image_metadata]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/_schedule.py
@@ -28,7 +28,7 @@ class ComputeStartStopSchedule(RestTranslatableMixin):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+        .. literalinclude:: ../samples/ml_samples_compute.py
             :start-after: [START compute_start_stop_schedule]
             :end-before: [END compute_start_stop_schedule]
             :language: python
@@ -120,7 +120,7 @@ class ComputeSchedules(RestTranslatableMixin):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+        .. literalinclude:: ../samples/ml_samples_compute.py
             :start-after: [START compute_start_stop_schedule]
             :end-before: [END compute_start_stop_schedule]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/aml_compute.py
@@ -38,7 +38,7 @@ class AmlComputeSshSettings:
 
     .. admonition:: Example:
 
-    .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+    .. literalinclude:: ../samples/ml_samples_compute.py
         :start-after: [START aml_compute_ssh_settings]
         :end-before: [END aml_compute_ssh_settings]
         :language: python
@@ -114,7 +114,7 @@ class AmlCompute(Compute):
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+        .. literalinclude:: ../samples/ml_samples_compute.py
             :start-after: [START amlcompute]
             :end-before: [END amlcompute]
             :language: python

diff --git a/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py b/sdk/ml/azure-ai-ml/azure/ai/ml/entities/_compute/compute.py
@@ -212,7 +212,7 @@ class NetworkSettings:
 
     .. admonition:: Example:
 
-        .. literalinclude:: ../../../../../samples/ml_samples_compute.py
+        .. literalinclude:: ../samples/ml_samples_compute.py
             :start-after: [START network_settings]
             :end-before: [END network_settings]
             :language: python