[azure-core] fixes sphinx paths and some docstring formatting

sdk/core/azure-core/azure/core/async_paging.py

@@ -31,7 +31,9 @@
 class AsyncPagedMixin(AsyncIterator):
     """Bring async to Paging.
 
-    :param async_command: Mandatory keyword argument for this mixin to work.
+    **Keyword argument:**
+
+    *async_command* - Mandatory keyword argument for this mixin to work.
     """
     def __init__(self, *args, **kwargs): # pylint: disable=unused-argument
         self._async_get_next = kwargs.get("async_command")

sdk/core/azure-core/azure/core/configuration.py

@@ -50,7 +50,7 @@ class Configuration(object):
      TrioRequestsTransport, AioHttpTransport.
 
     Example:
-        .. literalinclude:: ../../examples/examples_config.py
+        .. literalinclude:: ../examples/examples_config.py
             :start-after: [START configuration]
             :end-before: [END configuration]
             :language: python
@@ -92,7 +92,7 @@ def __init__(self, transport=None, **kwargs):
 class ConnectionConfiguration(object):
     """HTTP transport connection configuration settings.
 
-    Common properies that can be configured on all transports. Found in the
+    Common properties that can be configured on all transports. Found in the
     Configuration object.
 
     :param int connection_timeout: The connect and read timeout value. Defaults to 100 seconds.
@@ -103,7 +103,7 @@ class ConnectionConfiguration(object):
     :param int connection_data_block_size: The block size of data sent over the connection. Defaults to 4096 bytes.
 
     Example:
-        .. literalinclude:: ../../examples/examples_config.py
+        .. literalinclude:: ../examples/examples_config.py
             :start-after: [START connection_configuration]
             :end-before: [END connection_configuration]
             :language: python

sdk/core/azure-core/azure/core/exceptions.py

@@ -36,11 +36,14 @@ def raise_with_traceback(exception, *args, **kwargs):
     # type: (Callable, Any, Any) -> None
     """Raise exception with a specified traceback.
     This MUST be called inside a "except" clause.
+
     :param Exception exception: Error type to be raised.
     :param args: Any additional args to be included with exception.
     :param kwargs: Keyword arguments to include with the exception.
-    Keyword arguments:
-    message Message to be associated with the exception. If omitted, defaults to an empty string.
+
+    **Keyword argument:**
+
+    *message (str)* - Message to be associated with the exception. If omitted, defaults to an empty string.
     """
     message = kwargs.pop('message', '')
     exc_type, exc_value, exc_traceback = sys.exc_info()
@@ -95,8 +98,9 @@ class ServiceResponseError(AzureError):
 
 class HttpResponseError(AzureError):
     """A request was made, and a non-success status code was received from the service.
-    :ivar status_code: HttpResponse's status code
-    :ivar response: The response that triggered the exception.
+
+    :param status_code: HttpResponse's status code
+    :param response: The response that triggered the exception.
     """
 
     def __init__(self, message=None, response=None, **kwargs):

sdk/core/azure-core/azure/core/paging.py

@@ -46,7 +46,8 @@ class AsyncPagedMixin(object):  # type: ignore
 class Paged(AsyncPagedMixin, Iterator):
     """A container for paged REST responses.
 
-    :param HttpResponse response: server response object.
+    :param response: server response object.
+    :type response: ~azure.core.pipeline.transport.HttpResponse
     :param callable command: Function to retrieve the next page of items.
     :param Deserializer deserializer: a Deserializer instance to use
     """

sdk/core/azure-core/azure/core/pipeline/__init__.py

@@ -50,8 +50,7 @@ def __exit__(self, exc_type, exc_value, traceback):
 
 
 class PipelineContext(dict):
-    """A context object carried by the pipeline request and
-     response containers.
+    """A context object carried by the pipeline request and response containers.
 
     This is transport specific and can contain data persisted between
     pipeline requests (for example reusing an open connection pool or "session"),
@@ -77,12 +76,22 @@ def __delitem__(self, key):
         return super(PipelineContext, self).__delitem__(key)
 
     def clear(self):
+        """Context objects cannot be cleared.
+
+        :raises: TypeError
+        """
         raise TypeError("Context objects cannot be cleared.")
 
     def update(self, *args, **kwargs):
+        """Context objects cannot be updated.
+
+        :raises: TypeError
+        """
         raise TypeError("Context objects cannot be updated.")
 
     def pop(self, *args):
+        """Removes specified key and returns the value.
+        """
         if args and args[0] in self._protected:
             raise ValueError('Context value {} cannot be popped.'.format(args[0]))
         return super(PipelineContext, self).pop(*args)

sdk/core/azure-core/azure/core/pipeline/policies/base.py

@@ -46,7 +46,7 @@ class HTTPPolicy(ABC, Generic[HTTPRequestType, HTTPResponseType]): # type: ignor
 
     :param next: Use to process the next policy in the pipeline. Set when pipeline is
      instantiated and all policies chained.
-    :type next: HTTPPolicy or HTTPTransport
+    :type next: ~azure.core.pipeline.policies.HTTPPolicy or ~azure.core.pipeline.transport.HTTPTransport
     """
     def __init__(self):
         self.next = None
@@ -108,7 +108,7 @@ def on_exception(self, _request, **kwargs):  #pylint: disable=unused-argument
         :rtype: bool
 
         Example:
-            .. literalinclude:: ../../../../examples/examples_sansio.py
+            .. literalinclude:: ../examples/examples_sansio.py
                 :start-after: [START on_exception]
                 :end-before: [END on_exception]
                 :language: python

sdk/core/azure-core/azure/core/pipeline/policies/base_async.py

@@ -56,7 +56,7 @@ class AsyncHTTPPolicy(abc.ABC, Generic[HTTPRequestType, AsyncHTTPResponseType]):
 
     :param next: Use to process the next policy in the pipeline. Set when pipeline
      is instantiated and all policies chained.
-    :type next: AsyncHTTPPolicy or AsyncHttpTransport
+    :type next: ~azure.core.pipeline.policies.AsyncHTTPPolicy or ~azure.core.pipeline.transport.AsyncHttpTransport
     """
     def __init__(self) -> None:
         # next will be set once in the pipeline

sdk/core/azure-core/azure/core/pipeline/policies/custom_hook.py

@@ -33,8 +33,9 @@ class CustomHookPolicy(SansIOHTTPPolicy):
     """A simple policy that enable the given callback
     with the response.
 
-    Keyword argument:
-    :param raw_response_hook: Callback function. Will be invoked on response.
+    **Keyword argument:**
+
+    *raw_response_hook* - Callback function. Will be invoked on response.
     """
     def __init__(self, **kwargs): # pylint: disable=unused-argument
         self._callback = None

sdk/core/azure-core/azure/core/pipeline/policies/redirect.py

@@ -47,12 +47,14 @@ class RedirectPolicy(HTTPPolicy):
 
     A redirect policy in the pipeline can be configured directly or per operation.
 
-    Keyword arguments:
-    :param redirects_allow: Whether the client allows redirects. Defaults to True.
-    :param redirect_max: The maximum allowed redirects. Defaults to 30.
+    **Keyword arguments:**
+
+    *redirects_allow (int)* - Whether the client allows redirects. Defaults to True.
+
+    *redirect_max (int)* - The maximum allowed redirects. Defaults to 30.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sync.py
+        .. literalinclude:: ../examples/examples_sync.py
             :start-after: [START redirect_policy]
             :end-before: [END redirect_policy]
             :language: python
@@ -142,8 +144,8 @@ def increment(self, settings, response, redirect_location):
         return settings['redirects'] > 0 or not settings['allow']
 
     def send(self, request):
-        """Sends the PipelineRequest object to the next policy. Uses redirect settings
-         to send request to redirect endpoint if necessary.
+        """Sends the PipelineRequest object to the next policy.
+        Uses redirect settings to send request to redirect endpoint if necessary.
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest

sdk/core/azure-core/azure/core/pipeline/policies/redirect_async.py

@@ -35,12 +35,14 @@ class AsyncRedirectPolicy(RedirectPolicy, AsyncHTTPPolicy):  # type: ignore
 
     An async redirect policy in the pipeline can be configured directly or per operation.
 
-    Keyword arguments:
-    :param redirects_allow: Whether the client allows redirects. Defaults to True.
-    :param redirect_max: The maximum allowed redirects. Defaults to 30.
+    **Keyword arguments:**
+
+    *redirects_allow (int)* - Whether the client allows redirects. Defaults to True.
+
+    *redirect_max (int)* - The maximum allowed redirects. Defaults to 30.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_async.py
+        .. literalinclude:: ../examples/examples_async.py
             :start-after: [START async_redirect_policy]
             :end-before: [END async_redirect_policy]
             :language: python
@@ -49,8 +51,8 @@ class AsyncRedirectPolicy(RedirectPolicy, AsyncHTTPPolicy):  # type: ignore
     """
 
     async def send(self, request):
-        """Sends the PipelineRequest object to the next policy. Uses redirect settings
-        to send the request to redirect endpoint if necessary.
+        """Sends the PipelineRequest object to the next policy.
+        Uses redirect settings to send the request to redirect endpoint if necessary.
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest

sdk/core/azure-core/azure/core/pipeline/policies/retry.py

@@ -50,25 +50,31 @@ class RetryPolicy(HTTPPolicy):
 
     The retry policy in the pipeline can be configured directly, or tweaked on a per-call basis.
 
-    Keyword arguments:
-    :param int retry_total: Total number of retries to allow. Takes precedence over other counts.
-     Default value is 10.
-    :param int retry_connect: How many connection-related errors to retry on.
-     These are errors raised before the request is sent to the remote server,
-     which we assume has not triggered the server to process the request. Default value is 3.
-    :param int retry_read: How many times to retry on read errors.
-     These errors are raised after the request was sent to the server, so the
-     request may have side-effects. Default value is 3.
-    :param int retry_status: How many times to retry on bad status codes. Default value is 3.
-    :param int retry_backoff_factor: A backoff factor to apply between attempts after the second try
-     (most errors are resolved immediately by a second try without a delay).
-     Retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
-     seconds. If the backoff_factor is 0.1, then the retry will sleep
-     for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
-    :param int retry_backoff_max: The maximum back off time. Default value is 120 seconds (2 minutes).
+    **Keyword arguments:**
+
+    *retry_total (int)* - Total number of retries to allow. Takes precedence over other counts.
+    Default value is 10.
+
+    *retry_connect (int)* - How many connection-related errors to retry on.
+    These are errors raised before the request is sent to the remote server,
+    which we assume has not triggered the server to process the request. Default value is 3.
+
+    *retry_read (int)* - How many times to retry on read errors.
+    These errors are raised after the request was sent to the server, so the
+    request may have side-effects. Default value is 3.
+
+    *retry_status (int)* - How many times to retry on bad status codes. Default value is 3.
+
+    *retry_backoff_factor (float)* - A backoff factor to apply between attempts after the second try
+    (most errors are resolved immediately by a second try without a delay).
+    Retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
+    seconds. If the backoff_factor is 0.1, then the retry will sleep
+    for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
+
+    *retry_backoff_max (int)* - The maximum back off time. Default value is 120 seconds (2 minutes).
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sync.py
+        .. literalinclude:: ../examples/examples_sync.py
             :start-after: [START retry_policy]
             :end-before: [END retry_policy]
             :language: python
@@ -252,7 +258,7 @@ def is_retry(self, settings, response):
 
         :param dict settings: The retry settings.
         :param response: The PipelineResponse object
-        :type response: ~azure.core.pipeline.PipelineResponse.
+        :type response: ~azure.core.pipeline.PipelineResponse
         :return: True if method/status code is retryable. False if not retryable.
         :rtype: bool
         """
@@ -325,8 +331,7 @@ def update_context(self, context, retry_settings):
             context['history'] = retry_settings['history']
 
     def send(self, request):
-        """Sends the PipelineRequest object to the next policy.
-         Uses retry settings if necessary.
+        """Sends the PipelineRequest object to the next policy. Uses retry settings if necessary.
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest

sdk/core/azure-core/azure/core/pipeline/policies/retry_async.py

@@ -44,25 +44,31 @@ class AsyncRetryPolicy(RetryPolicy, AsyncHTTPPolicy):  # type: ignore
 
     The async retry policy in the pipeline can be configured directly, or tweaked on a per-call basis.
 
-    Keyword arguments:
-    :param int retry_total: Total number of retries to allow. Takes precedence over other counts.
-     Default value is 10.
-    :param int retry_connect: How many connection-related errors to retry on.
-     These are errors raised before the request is sent to the remote server,
-     which we assume has not triggered the server to process the request. Default value is 3.
-    :param int retry_read: How many times to retry on read errors.
-     These errors are raised after the request was sent to the server, so the
-     request may have side-effects. Default value is 3.
-    :param int retry_status: How many times to retry on bad status codes. Default value is 3.
-    :param int retry_backoff_factor: A backoff factor to apply between attempts after the second try
-     (most errors are resolved immediately by a second try without a delay).
-     Retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
-     seconds. If the backoff_factor is 0.1, then the retry will sleep
-     for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
-    :param int retry_backoff_max: The maximum back off time. Default value is 120 seconds (2 minutes).
+    **Keyword arguments:**
+
+    *retry_total (int)* - Total number of retries to allow. Takes precedence over other counts.
+    Default value is 10.
+
+    *retry_connect (int)* - How many connection-related errors to retry on.
+    These are errors raised before the request is sent to the remote server,
+    which we assume has not triggered the server to process the request. Default value is 3.
+
+    *retry_read (int)* - How many times to retry on read errors.
+    These errors are raised after the request was sent to the server, so the
+    request may have side-effects. Default value is 3.
+
+    *retry_status (int)* - How many times to retry on bad status codes. Default value is 3.
+
+    *retry_backoff_factor (float)* - A backoff factor to apply between attempts after the second try
+    (most errors are resolved immediately by a second try without a delay).
+    Retry policy will sleep for: `{backoff factor} * (2 ** ({number of total retries} - 1))`
+    seconds. If the backoff_factor is 0.1, then the retry will sleep
+    for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
+
+    *retry_backoff_max (int)* - The maximum back off time. Default value is 120 seconds (2 minutes).
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_async.py
+        .. literalinclude:: ../examples/examples_async.py
             :start-after: [START async_retry_policy]
             :end-before: [END async_retry_policy]
             :language: python
@@ -114,14 +120,13 @@ async def sleep(self, settings, transport, response=None):
         await self._sleep_backoff(settings, transport)
 
     async def send(self, request):
-        """Uses the configured retry policy to send the request
-         to the next policy in the pipeline.
+        """Uses the configured retry policy to send the request to the next policy in the pipeline.
 
         :param request: The PipelineRequest object
         :type request: ~azure.core.pipeline.PipelineRequest
         :return: Returns the PipelineResponse or raises error if maximum retries exceeded.
         :rtype: ~azure.core.pipeline.PipelineResponse
-        :raises: ~azure.core.exceptions.AzureError if maximum retries exceeded.
+        :raise: ~azure.core.exceptions.AzureError if maximum retries exceeded.
         """
         retry_active = True
         response = None