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

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,9 +36,11 @@ 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.
     """
@@ -95,8 +97,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"),

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

@@ -34,7 +34,8 @@ class CustomHookPolicy(SansIOHTTPPolicy):
     with the response.
 
     Keyword argument:
-    :param raw_response_hook: Callback function. Will be invoked on response.
+
+    *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

@@ -48,11 +48,12 @@ 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.
 
     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 +143,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

@@ -36,11 +36,12 @@ 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.
 
     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 +50,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

@@ -51,6 +51,7 @@ 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.
@@ -68,7 +69,7 @@ class RetryPolicy(HTTPPolicy):
     :param int retry_backoff_max: 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 +253,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 +326,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

@@ -45,6 +45,7 @@ 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.
@@ -62,7 +63,7 @@ class AsyncRetryPolicy(RetryPolicy, AsyncHTTPPolicy):  # type: ignore
     :param int retry_backoff_max: 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,8 +115,7 @@ 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

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

@@ -61,7 +61,7 @@ class HeadersPolicy(SansIOHTTPPolicy):
     :param dict base_headers: Headers to send with the request.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sansio.py
+        .. literalinclude:: ../examples/examples_sansio.py
             :start-after: [START headers_policy]
             :end-before: [END headers_policy]
             :language: python
@@ -107,7 +107,7 @@ class UserAgentPolicy(SansIOHTTPPolicy):
     :param bool user_agent_use_env: Keyword argument that gets user-agent from environment. Defaults to True.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sansio.py
+        .. literalinclude:: ../examples/examples_sansio.py
             :start-after: [START user_agent_policy]
             :end-before: [END user_agent_policy]
             :language: python
@@ -180,7 +180,7 @@ class NetworkTraceLoggingPolicy(SansIOHTTPPolicy):
      Defaults to False.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sansio.py
+        .. literalinclude:: ../examples/examples_sansio.py
             :start-after: [START network_trace_logging_policy]
             :end-before: [END network_trace_logging_policy]
             :language: python
@@ -278,6 +278,7 @@ def deserialize_from_text(cls, response, content_type=None):
         """Decode response data according to content-type.
         Accept a stream of data as well, but will be load at once in memory for now.
         If no content-type, will return the string version (not bytes, not stream)
+
         :param response: The HTTP response.
         :type response: ~azure.core.pipeline.transport.HttpResponse
         :param str content_type: The content type.
@@ -389,7 +390,7 @@ class ProxyPolicy(SansIOHTTPPolicy):
      from environment. Defaults to True.
 
     Example:
-        .. literalinclude:: ../../../../examples/examples_sansio.py
+        .. literalinclude:: ../examples/examples_sansio.py
             :start-after: [START proxy_policy]
             :end-before: [END proxy_policy]
             :language: python

sdk/core/azure-core/azure/core/pipeline/transport/aiohttp.py

@@ -119,14 +119,14 @@ async def send(self, request: HttpRequest, **config: Any) -> Optional[AsyncHttpR
         Will pre-load the body into memory to be available with a sync method.
         pass stream=True to avoid this behavior.
 
+        Keyword arguments:
+        *stream* - Defaults to False.
+
         :param request: The HttpRequest object
         :type request: ~azure.core.pipeline.transport.HttpRequest
         :param config: Any keyword arguments
         :return: The AsyncHttpResponse
         :rtype: ~azure.core.pipeline.transport.AsyncHttpResponse
-
-        Keyword arguments:
-        stream - Defaults to False.
         """
         await self.open()
         error = None

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

@@ -288,6 +288,7 @@ def _request(
         ):
         # type: (...) -> HttpRequest
         """Create HttpRequest object.
+
         :param str method: HTTP method (GET, HEAD, etc.)
         :param str url: URL for the request.
         :param dict params: URL query parameters.
@@ -336,6 +337,7 @@ def format_url(self, url_template, **kwargs):
         # type: (str, Any) -> str
         """Format request URL with the client base URL, unless the
         supplied URL is already absolute.
+
         :param str url_template: The request URL to be formatted if necessary.
         """
         url = self._format_url_section(url_template, **kwargs)
@@ -358,6 +360,7 @@ def get(
         ):
         # type: (...) -> HttpRequest
         """Create a GET request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -379,6 +382,7 @@ def put(
         ):
         # type: (...) -> HttpRequest
         """Create a PUT request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -399,6 +403,7 @@ def post(
         ):
         # type: (...) -> HttpRequest
         """Create a POST request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -419,6 +424,7 @@ def head(
         ):
         # type: (...) -> HttpRequest
         """Create a HEAD request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -439,6 +445,7 @@ def patch(
         ):
         # type: (...) -> HttpRequest
         """Create a PATCH request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -452,6 +459,7 @@ def patch(
     def delete(self, url, params=None, headers=None, content=None, form_content=None):
         # type: (str, Optional[Dict[str, str]], Optional[Dict[str, str]], Any, Optional[Dict[str, Any]]) -> HttpRequest
         """Create a DELETE request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers
@@ -465,6 +473,7 @@ def delete(self, url, params=None, headers=None, content=None, form_content=None
     def merge(self, url, params=None, headers=None, content=None, form_content=None):
         # type: (str, Optional[Dict[str, str]], Optional[Dict[str, str]], Any, Optional[Dict[str, Any]]) -> HttpRequest
         """Create a MERGE request object.
+
         :param str url: The request URL.
         :param dict params: Request URL parameters.
         :param dict headers: Headers

sdk/core/azure-core/azure/core/pipeline/transport/requests_basic.py

@@ -192,9 +192,10 @@ def send(self, request, **kwargs): # type: ignore
         # type: (HttpRequest, Any) -> HttpResponse
         """Send request object according to configuration.
 
-        Allowed kwargs are:
-        - session : will override the driver session and use yours. Should NOT be done unless really required.
-        - anything else is sent straight to requests.
+        Keyword arguments:
+
+        *session* - will override the driver session and use yours. Should NOT be done unless really required.
+        Anything else is sent straight to requests.
 
         :param request: The request object to be sent.
         :type request: ~azure.core.pipeline.transport.HttpRequest

sdk/core/azure-core/azure/core/pipeline_client.py

@@ -49,13 +49,13 @@ class PipelineClient(PipelineClientBase):
     :rtype: ~azure.core.pipeline.Pipeline
 
     Keyword arguments:
-    pipeline - A Pipeline object. If omitted, a Pipeline object is created
-     and returned.
-    transport - The HTTP Transport type. If omitted, RequestsTransport is used
-     for synchronous transport.
+
+    *pipeline* - A Pipeline object. If omitted, a Pipeline object is created and returned.
+
+    *transport* - The HTTP Transport type. If omitted, RequestsTransport is used for synchronous transport.
 
     Example:
-        .. literalinclude:: ../../examples/examples_sync.py
+        .. literalinclude:: ../examples/examples_sync.py
             :start-after: [START build_pipeline_client]
             :end-before: [END build_pipeline_client]
             :language: python