[ml][ai] Turn on docstring validation (#33248)

* Turn on docstring validation

* Remove whitespace

* Resolve ai packages sphinx errors

* Resolve ml packages sphinx errors

* Resolve some ml sphinx errors

* Fix remaining sphinx errors

* Fix generative error

* Make pylint mandatory

* Fix some ml sphinx errors

* Enable pylint check for docstring errors

* Enable pylint check for docstring errors

* Update ml and generative pyproject.toml files

* Update syntax for enable/disable in pylint pyproject.toml sections

* Try using disable config only

* Disable pylint - will address in another PR

* Revert init changes

* Update sweep_job and _feature_set_operations

* Turn off strict_sphinx check for azure-ai-ml

* Fix sphinx issue in _custom_metric.py

* Update name of job operations begin cancel sample

* Reformat service_client param in model_operations method

Author: diondrapeck

sdk/ai/azure-ai-generative/README.md

@@ -23,7 +23,7 @@ For a more complete set of Azure libraries, see https://aka.ms/azsdk/python/all.
 ### Install the package
 Install the Azure AI generative package for Python with pip:
 
-```dotnetcli
+```
 pip install azure-ai-generative[index,evaluate,promptflow]
 pip install azure-identity
 ```
@@ -131,7 +131,6 @@ If you encounter any bugs or have suggestions, please file an issue in the [Issu
 [azure_core_ref_docs]: https://aka.ms/azsdk-python-core-policies
 [azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
 [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
-[python_logging]: https://docs.python.org/3/library/logging.html
 [cla]: https://cla.microsoft.com
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/

sdk/ai/azure-ai-generative/azure/ai/generative/evaluate/metrics/_custom_metric.py

@@ -20,45 +20,43 @@ def __init__(self, name):
 class CodeMetric(Metric):
     """Evaluation code metric
 
-        :keyword name: Name of the metric.
-        :paramtype name: str
-        :keyword calculate: Function to compute row level metrics. It should have the following signature:
-
-            .. code-block:: python
-
-                def my_code_metric(
-                    *,
-                    data: Dict,
-                    response: Union[Dict, str],
-                    **kwargs,
-                ):
-                    '''
-                        :keyword data: Row data.This method will be called for each row.
-                        :paramtype data: Dict
-                        :keyword response: Response from target function passed to evaluate API otherwise None.
-                        :paramtype response: Dict
-                        :keyword kwargs: Includes params like data_mapping for this metric passed to evaluate API.
-                        :paramtype kwargs: Dict
-                    '''
-                ...
-        :paramtype calculate: Callable
-        :keyword aggregator: Function to aggregate row level metrics. It should have the following signature:
-            .. code-block:: python
-
-                def my_aggregator(
-                    *,
-                    values,
-                    **kwargs,
-                ):
-                    '''
-                        :keyword values: Row level metric value calculated by calculate method of the metric.
-                        :paramtype values: Union[int, Dict[str, int]]
-                        :keyword kwargs: Includes params like data_mapping for this metric passed to evaluate API.
-                        :paramtype kwargs: Dict
-                    '''
-                ...
-        :paramtype aggregator: Callable
-
+    :keyword name: Name of the metric.
+    :paramtype name: str
+    :keyword calculate: Function to compute row level metrics. It should have the following signature:
+
+        .. code:: python
+
+            def my_code_metric(
+                data: Dict,
+                response: Union[Dict, str],
+                **kwargs,
+            ):
+                '''
+                :keyword data: Row data. This method will be called for each row.
+                :paramtype data: Dict
+                :keyword response: Response from target function passed to evaluate API otherwise None.
+                :paramtype response: Dict
+                :keyword kwargs: Includes params like data_mapping for this metric passed to evaluate API.
+                :paramtype kwargs: Dict
+                '''
+
+    :paramtype calculate: Callable
+    :keyword aggregator: Function to aggregate row level metrics. It should have the following signature:
+
+        .. code:: python
+
+            def my_aggregator(
+                values: Union[int, Dict[str, int]],
+                **kwargs,
+            ):
+                '''
+                :keyword values: Row level metric value calculated by calculate method of the metric.
+                :paramtype values: Union[int, Dict[str, int]]
+                :keyword kwargs: Includes params like data_mapping for this metric passed to evaluate API.
+                :paramtype kwargs: Dict
+                '''
+
+    :paramtype aggregator: Callable
     """
 
     def __init__(self, *, name, calculate, aggregator=None, **kwargs):

sdk/ai/azure-ai-generative/azure/ai/generative/synthetic/qa.py

@@ -260,10 +260,9 @@ def _modify_conversation_questions(self, questions) -> Tuple[List[str], Dict]:
     @distributed_trace
     @monitor_with_activity(logger, "QADataGenerator.Export", ActivityType.INTERNALCALL)
     def export_to_file(self, output_path: str, qa_type: QAType, results: Union[List, List[List]], output_format: OutputStructure = OutputStructure.PROMPTFLOW, field_mapping: Dict[str,str] = {"chat_history_key": "chat_history", "question_key": "question"}):
-        """
-            Writes results from QA gen to a jsonl file for Promptflow batch run
-            results is either a list of questions and answers or list of list of questions and answers grouped by their chunk
-                e.g. [("How are you?", "I am good.")]    or [ [("How are you?", "I am good.")], [("What can I do?", "Tell me a joke.")]
+        """Writes results from QA gen to a jsonl file for Promptflow batch run results is either a list of questions
+        and answers or list of list of questions and answers grouped by their chunk e.g. [("How are you?",
+        "I am good.")] or [ [("How are you?", "I am good.")], [("What can I do?", "Tell me a joke.")]
         """
         data_dict = defaultdict(list)
 

sdk/ai/azure-ai-generative/pyproject.toml

@@ -9,6 +9,7 @@ bandit = false
 sphinx=true
 breaking = false
 whl_no_aio = false
+strict_sphinx = true
 
 [tool.mypy] 
 python_version = "3.10"

sdk/ai/azure-ai-resources/README.md

@@ -24,7 +24,7 @@ For a more complete set of Azure libraries, see https://aka.ms/azsdk/python/all.
 ### Install the package
 Install the Azure AI generative package for Python with pip:
 
-```dotnetcli
+```
 pip install azure-ai-resources
 pip install azure-identity
 ```
@@ -97,7 +97,6 @@ If you encounter any bugs or have suggestions, please file an issue in the [Issu
 [azure_core_ref_docs]: https://aka.ms/azsdk-python-core-policies
 [azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
 [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
-[python_logging]: https://docs.python.org/3/library/logging.html
 [cla]: https://cla.microsoft.com
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/

sdk/ai/azure-ai-resources/azure/ai/resources/constants/_common.py

@@ -31,8 +31,7 @@ class IndexType(object):
     FAISS = "faiss"
 
 class OperationScope:
-    """
-        Some AI Client Operations can be applied to either the client's AI resource,
+    """Some AI Client Operations can be applied to either the client's AI resource
     or its project. For such operations, this is used to determine that scope.
     """
     AI_RESOURCE = "ai_resource"

sdk/ai/azure-ai-resources/azure/ai/resources/entities/base_connection.py

@@ -32,8 +32,7 @@ class BaseConnection:
     :param id: The connection's resource id.
     :type id: str
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
 
@@ -79,10 +78,10 @@ def _from_v2_workspace_connection(cls, workspace_connection: WorkspaceConnection
 
     @classmethod
     def _get_ai_connection_class_from_type(cls,  conn_type: str):
-        ''' Given a connection type string, get the corresponding AI SDK object via class
+        """Given a connection type string, get the corresponding AI SDK object via class
         comparisons. Accounts for any potential camel/snake/capitalization issues. Returns
         the BaseConnection class if no match is found.
-        '''
+        """
         #import here to avoid circular import
         from .connection_subtypes import (
             AzureOpenAIConnection,
@@ -194,7 +193,7 @@ def credentials(self, value: ApiKeyConfiguration):  # Eventual TODO: re-add Mana
 
     @property
     def tags(self) -> Dict[str, Any]:
-        """tags for the connection.
+        """Tags for the connection.
 
         :return: This connection's tags.
         :rtype: Dict[str, Any]
@@ -236,26 +235,26 @@ def metadata(self, value: Dict[str, Any]):
 
     @property
     def is_shared(self) -> bool:
-        """Get the Boolean describing if this connection is shared
-            amongst its cohort within a workspace hub. Only applicable for connections
-            that are project-scoped on creation.
+        """Get the Boolean describing if this connection is shared amongst its cohort within a workspace hub.
+        Only applicable for connections that are project-scoped on creation.
+
         :rtype: bool
         """
         return self._workspace_connection.is_shared
 
     @is_shared.setter
     def is_shared(self, value: bool):
-        """The is_shared determines if this connection is shared amongst other
-            lean workspaces within its parent workspace hub. Only applicable for connections
-            that are project-scoped on creation.
+        """The is_shared determines if this connection is shared amongst other lean workspaces within its parent
+        workspace hub. Only applicable for connections that are project-scoped on creation.
+
         :type value: bool
         """
         if not value:
             return
         self._workspace_connection.is_shared = value
 
     def set_current_environment(self, credential: Optional[TokenCredential] = None):
-        """Sets the current environment to use the connection. To use AAD auth for AzureOpenAI connetion, pass in a credential object.
+        """Sets the current environment to use the connection. To use AAD auth for AzureOpenAI connection, pass in a credential object.
         Only certain types of connections make use of this function. Those that don't will raise an error if this is called.
 
         :param credential: Optional credential to use for the connection. If not provided, the connection's credentials will be used.

sdk/ai/azure-ai-resources/azure/ai/resources/entities/connection_subtypes.py

@@ -34,8 +34,7 @@ class AzureOpenAIConnection(BaseConnection):
     :param api_type: The api type that this connection was created for. Defaults to "Azure" and currently rarely changes.
     :type api_type: str
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
 
@@ -162,8 +161,7 @@ class AzureAISearchConnection(BaseConnection):
     :param api_version: The api version that this connection was created for. Only applies to certain connection types.
     :type api_version: Optional[str]
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
 
@@ -233,11 +231,10 @@ class AzureAIServiceConnection(BaseConnection):
     :param api_version: The api version that this connection was created for.
     :type api_version: Optional[str]
     :param kind: The kind of ai service that this connection points to. Valid inputs include:
-        "AzureOpenAI", "ContentSafety", and "Speech"
+        "AzureOpenAI", "ContentSafety", and "Speech".
     :type kind: str
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
 
@@ -305,8 +302,7 @@ class GitHubConnection(BaseConnection):
     :param credentials: The credentials for authenticating the external resource.
     :type credentials: ~azure.ai.ml.entities.ApiKeyConfiguration
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
 
@@ -332,8 +328,7 @@ class CustomConnection(BaseConnection):
     :param credentials: The credentials for authenticating the external resource.
     :type credentials: ~azure.ai.ml.entities.ApiKeyConfiguration
     :param is_shared: For connections created for a project, this determines if the connection
-        is shared amongst other connections with that project's parent AI resource.
-        Defaults to true.
+        is shared amongst other connections with that project's parent AI resource. Defaults to True.
     :type is_shared: bool
     """
     def __init__(

sdk/ai/azure-ai-resources/azure/ai/resources/operations/_ai_resource_operations.py

@@ -40,7 +40,7 @@ def get(self, *, name: str, **kwargs) -> AIResource:
         :paramtype name: str
 
         :return: The AI resource with the provided name.
-        :rtype: AIResource
+        :rtype: ~azure.ai.resources.entities.AIResource
         """
         workspace_hub = self._ml_client._workspace_hubs.get(name=name, **kwargs)
         resource = AIResource._from_v2_workspace_hub(workspace_hub)
@@ -55,7 +55,7 @@ def list(self, *, scope: str = Scope.RESOURCE_GROUP) -> Iterable[AIResource]:
         :paramtype scope: str
 
         :return: An iterator like instance of AI resource objects
-        :rtype: Iterable[AIResource]
+        :rtype: Iterable[~azure.ai.resources.entities.AIResource]
         """
         return [AIResource._from_v2_workspace_hub(wh) for wh in self._ml_client._workspace_hubs.list(scope=scope)]
 

sdk/ai/azure-ai-resources/azure/ai/resources/operations/_project_operations.py

@@ -47,7 +47,7 @@ def get(self, *, name: Optional[str] = None, **kwargs: Dict) -> Project:
         :keyword name: Name of the project.
         :paramtype name: str
         :return: The project with the provided name.
-        :rtype: Project
+        :rtype: ~azure.ai.resource.entities.Project
         """
 
         workspace = self._ml_client._workspaces.get(name=name, **kwargs)
@@ -62,7 +62,7 @@ def list(self, *, scope: str = Scope.RESOURCE_GROUP) -> Iterable[Project]:
         :keyword scope: The scope of the listing. Can be either "resource_group" or "subscription", and defaults to "resource_group".
         :paramtype scope: str
         :return: An iterator like instance of Project objects
-        :rtype: Iterable[Project]
+        :rtype: Iterable[~azure.ai.resource.entities.Project]
         """
 
         workspaces = []