From 8f9e77088f1997838504ec368cf6f37847a17f29 Mon Sep 17 00:00:00 2001
From: Paul Van Eck <paulvaneck@microsoft.com>
Date: Mon, 17 Oct 2022 10:12:41 -0700
Subject: [PATCH] [Identity] Doc formatting fixes (#26664)

- Fixed a few issues with docs not being rendered as expected
  on the api docs website.
- Added a note in the DAC troubleshooting section for users
  who are directed there from an error regarding
  additionally_allowed_tenants configuration.

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>
---
 .../azure-identity/TROUBLESHOOTING.md         |  2 +-
 .../identity/_credentials/client_assertion.py | 37 ++++++++++---------
 .../azure/identity/_persistent_cache.py       |  2 +
 .../aio/_credentials/client_assertion.py      | 37 ++++++++++---------
 4 files changed, 41 insertions(+), 37 deletions(-)

diff --git a/sdk/identity/azure-identity/TROUBLESHOOTING.md b/sdk/identity/azure-identity/TROUBLESHOOTING.md
index a4aabad78c6d..8143e04fab0d 100644
--- a/sdk/identity/azure-identity/TROUBLESHOOTING.md
+++ b/sdk/identity/azure-identity/TROUBLESHOOTING.md
@@ -82,7 +82,7 @@ See full SDK logging documentation with examples [here][sdk_logging_docs].
 | Error |Description| Mitigation |
 |---|---|---|
 |`CredentialUnavailableError` raised with message. "DefaultAzureCredential failed to retrieve a token from the included credentials."|All credentials in the `DefaultAzureCredential` chain failed to retrieve a token, each raising a `CredentialUnavailableError` themselves|<ul><li>[Enable logging](#logging) to verify the credentials being tried, and get further diagnostic information.</li><li>Consult the troubleshooting guide for underlying credential types for more information.</li><ul><li>[EnvironmentCredential](#troubleshoot-environmentcredential-authentication-issues)</li><li>[ManagedIdentityCredential](#troubleshoot-managedidentitycredential-authentication-issues)</li><li>[VisualStudioCodeCredential](#troubleshoot-visualstudiocodecredential-authentication-issues)</li><li>[AzureCLICredential](#troubleshoot-azureclicredential-authentication-issues)</li><li>[AzurePowershellCredential](#troubleshoot-azurepowershellcredential-authentication-issues)</li></ul>|
-|`ClientAuthenticationError` raised from the client with a status code of 401 or 403|Authentication succeeded but the authorizing Azure service responded with a 401 (Authenticate), or 403 (Forbidden) status code. This can often be caused by the `DefaultAzureCredential` authenticating an account other than the intended one.|<ul><li>[Enable logging](#logging) to determine which credential in the chain returned the authenticating token.</li><li>In the case a credential other than the expected is returning a token, bypass this by either signing out of the corresponding development tool, or excluding the credential with an `exclude_xxx_credential` keyword argument when creating `DefaultAzureCredential`</li></ul>|
+|`ClientAuthenticationError` raised from the client with a status code of 401 or 403|Authentication succeeded but the authorizing Azure service responded with a 401 (Authenticate), or 403 (Forbidden) status code. This can often be caused by the `DefaultAzureCredential` authenticating an account other than the intended one.|<ul><li>[Enable logging](#logging) to determine which credential in the chain returned the authenticating token.</li><li>In the case a credential other than the expected is returning a token, bypass this by either signing out of the corresponding development tool, or excluding the credential with an `exclude_xxx_credential` keyword argument when creating `DefaultAzureCredential`.</li><li>Consult the [troubleshooting guide](#troubleshoot-multi-tenant-authentication-issues) for multi-tenant authentication issues if an error is encountered stating the current credential is not configured to acquire tokens for a tenant.</li></ul>|
 
 ## Troubleshoot `EnvironmentCredential` authentication issues
 
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py b/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py
index 1faa9552c0eb..482f76cdb106 100644
--- a/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py
+++ b/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py
@@ -13,26 +13,27 @@
 
 
 class ClientAssertionCredential(GetTokenMixin):
+    """Authenticates a service principal with a JWT assertion.
+
+    This credential is for advanced scenarios. :class:`~azure.identity.ClientCertificateCredential` has a more
+    convenient API for the most common assertion scenario, authenticating a service principal with a certificate.
+
+    :param str tenant_id: ID of the principal's tenant. Also called its "directory" ID.
+    :param str client_id: The principal's client ID
+    :param func: A callable that returns a string assertion. The credential will call this every time it
+        acquires a new token.
+    :paramtype func: Callable[[], str]
+
+    :keyword str authority: Authority of an Azure Active Directory endpoint, for example
+        "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
+        :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
+    """
+
     def __init__(self, tenant_id, client_id, func, **kwargs):
         # type: (str, str, Callable[[], str], **Any) -> None
-        """Authenticates a service principal with a JWT assertion.
-
-        This credential is for advanced scenarios. :class:`~azure.identity.ClientCertificateCredential` has a more
-        convenient API for the most common assertion scenario, authenticating a service principal with a certificate.
-
-        :param str tenant_id: ID of the principal's tenant. Also called its "directory" ID.
-        :param str client_id: The principal's client ID
-        :param func: A callable that returns a string assertion. The credential will call this every time it
-            acquires a new token.
-        :paramtype func: Callable[[], str]
-
-        :keyword str authority: Authority of an Azure Active Directory endpoint, for example
-            "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
-            :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
-        :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
-            for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
-            acquire tokens for any tenant the application can access.
-        """
         self._func = func
         self._client = AadClient(tenant_id, client_id, **kwargs)
         super(ClientAssertionCredential, self).__init__(**kwargs)
diff --git a/sdk/identity/azure-identity/azure/identity/_persistent_cache.py b/sdk/identity/azure-identity/azure/identity/_persistent_cache.py
index 6c6765c5ad95..ca48fad59c6f 100644
--- a/sdk/identity/azure-identity/azure/identity/_persistent_cache.py
+++ b/sdk/identity/azure-identity/azure/identity/_persistent_cache.py
@@ -31,6 +31,8 @@ class TokenCachePersistenceOptions(object):
     .. warning:: The cache contains authentication secrets. If the cache is not encrypted, protecting it is the
        application's responsibility. A breach of its contents will fully compromise accounts.
 
+    .. admonition:: Example:
+
         .. literalinclude:: ../tests/test_persistent_cache.py
             :start-after: [START snippet]
             :end-before: [END snippet]
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py
index 62c8299e6ed7..a694ad890a66 100644
--- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py
+++ b/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py
@@ -13,25 +13,26 @@
 
 
 class ClientAssertionCredential(AsyncContextManager, GetTokenMixin):
+    """Authenticates a service principal with a JWT assertion.
+
+    This credential is for advanced scenarios. :class:`~azure.identity.ClientCertificateCredential` has a more
+    convenient API for the most common assertion scenario, authenticating a service principal with a certificate.
+
+    :param str tenant_id: ID of the principal's tenant. Also called its "directory" ID.
+    :param str client_id: The principal's client ID
+    :param func: A callable that returns a string assertion. The credential will call this every time it
+        acquires a new token.
+    :paramtype func: Callable[[], str]
+
+    :keyword str authority: Authority of an Azure Active Directory endpoint, for example
+        "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
+        :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
+    """
+
     def __init__(self, tenant_id: str, client_id: str, func: "Callable[[], str]", **kwargs: "Any") -> None:
-        """Authenticates a service principal with a JWT assertion.
-
-        This credential is for advanced scenarios. :class:`~azure.identity.ClientCertificateCredential` has a more
-        convenient API for the most common assertion scenario, authenticating a service principal with a certificate.
-
-        :param str tenant_id: ID of the principal's tenant. Also called its "directory" ID.
-        :param str client_id: The principal's client ID
-        :param func: A callable that returns a string assertion. The credential will call this every time it
-            acquires a new token.
-        :paramtype func: Callable[[], str]
-
-        :keyword str authority: Authority of an Azure Active Directory endpoint, for example
-            "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
-            :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
-        :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
-            for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
-            acquire tokens for any tenant the application can access.
-        """
         self._func = func
         self._client = AadClient(tenant_id, client_id, **kwargs)
         super().__init__(**kwargs)