Tweak documentation for credentials provider

alisaifee · Dec 4, 2024 · c39e8be · c39e8be
1 parent 313764b
commit c39e8be
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 8 deletions.
diff --git a/coredis/credentials.py b/coredis/credentials.py
@@ -6,7 +6,13 @@
 
 
 class UserPass(NamedTuple):
+    """
+    Username/password tuple.
+    """
+
+    #: Username
     username: str
+    #: Password
     password: str
 
 
@@ -17,6 +23,10 @@ class AbstractCredentialProvider(ABC):
 
     @abstractmethod
     async def get_credentials(self) -> UserPass:
+        """
+        Returns an instance of :class:`coredis.credentials.UserPass` for
+        establishing a connection to the redis server.
+        """
         pass
 
 

diff --git a/docs/source/api/credentials.rst b/docs/source/api/credentials.rst
@@ -14,5 +14,9 @@ Credential Providers
 .. autoclass:: coredis.credentials.UserPassCredentialProvider
    :class-doc-from: both
 
+.. autoclass:: coredis.credentials.UserPass
+   :no-inherited-members:
+
+
 .. autoclass:: coredis.recipes.credentials.ElastiCacheIAMProvider
-   :class-doc-from: both
+   :class-doc-from: both
diff --git a/docs/source/handbook/credentials.rst b/docs/source/handbook/credentials.rst
@@ -4,15 +4,15 @@ Credential Providers
 
 In addition to supplying a static username and/or password, **coredis** allows a credential provider
 to be specified. The **coredis** clients accept any credential provider implementing the
-:class:`coredis.credentials.AbstractCredentialProvider` interface. This allows clients to access
+:class:`~coredis.credentials.AbstractCredentialProvider` interface. This allows clients to access
 credentials stored in external credential providers such as AWS IAM.
 
 Using the Credential Provider
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 **coredis** comes with a basic implementation of the :class:`coredis.credentials.AbstractCredentialProvider`
-interface. This is :class:`coredis.credentials.UserPassCredentialProvider`. It allows a user
+interface. This is :class:`~coredis.credentials.UserPassCredentialProvider`. It allows a user
 to specify a username and/or password that will be used to authenticate with a redis instance.
-When the :method:`coredis.credentials.AbstractCredentialProvider.get_credentials` is called, the
+When the :meth:`~coredis.credentials.AbstractCredentialProvider.get_credentials` is called, the
 username and/or password that was set will be returned whenever **coredis** needs the credentials
 in order to authenticate with the redis or other server.
 

diff --git a/docs/source/handbook/index.rst b/docs/source/handbook/index.rst
@@ -7,6 +7,7 @@ Handbook
 
     cluster
     sentinel
+    credentials
     pubsub
     streams
     caching
@@ -21,7 +22,6 @@ Handbook
     typing
     development
 
-
 This section contains details on high level concepts
 of redis that are supported by **coredis**.
 
@@ -31,6 +31,10 @@ Deployment Topologies
 - :ref:`handbook/cluster:redis cluster`
 - :ref:`handbook/sentinel:sentinel support`
 
+Authentication
+--------------
+- :ref:`handbook/credentials:credential providers`
+
 Event Driven Architectures
 --------------------------
 - :ref:`handbook/pubsub:pubsub`

diff --git a/docs/source/recipes/credentials.rst b/docs/source/recipes/credentials.rst
@@ -5,10 +5,11 @@ Credential Providers
 Elasticache IAM Credential Provider
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The implementation is based on `the Elasticache IAM provider described in redis docs <https://redis-py.readthedocs.io/en/stable/examples/connection_examples.html#Connecting-to-a-redis-instance-with-ElastiCache-IAM-credential-provider>.`__
+The implementation is based on `the Elasticache IAM provider described in redis docs <https://redis-py.readthedocs.io/en/stable/examples/connection_examples.html#Connecting-to-a-redis-instance-with-ElastiCache-IAM-credential-provider\.>`__
 
-The :class:`ElastiCacheIAMProvider` implements the :class:`coredis.credentials.AbstractCredentialProvider`
-interface. It uses ``botocore`` to generate a short-lived authentication token
+The :class:`~coredis.recipes.credentials.ElastiCacheIAMProvider` implements the
+:class:`~coredis.credentials.AbstractCredentialProvider` interface.
+It uses :pypi:`botocore` to generate a short-lived authentication token
 which can be used to authenticate with an IAM enabled Elasticache cluster.
 The token is cached for its lifetime of 15 minutes to reduce the number
 of unnecessary requests.
@@ -18,4 +19,5 @@ on using IAM to authenticate with Elasticache.
 
 .. autoclass:: coredis.recipes.credentials.ElastiCacheIAMProvider
    :class-doc-from: both
+   :no-index:
 
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -10,4 +10,7 @@ sphinxext-opengraph==0.9.1
 sphinx-sitemap==2.5.1
 sphinx-paramlinks==0.6.0
 sphinxcontrib-programoutput==0.17
+# For credentials recipe
+botocore
+cachetools