From ddc1dc153b64b3c69b1569b46087c5d115418552 Mon Sep 17 00:00:00 2001
From: Correy Lim <correylim@gmail.com>
Date: Fri, 24 Apr 2020 09:38:12 -0700
Subject: [PATCH 1/3] Add code example for `aud` being an array

The previous code example only showed the `aud` claim as a single
case-sensitive string, despite the documentation mentioning that the
`aud` claim can be an array of case-sensitive strings

Add a code block demonstrating the `aud` claim being an array of
case-sensitive strings to make it more clear to the user that it is a
permitted use of the `aud` claim
---
 docs/usage.rst | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/usage.rst b/docs/usage.rst
index 131e67bc7..cdb84eb78 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -183,12 +183,23 @@ Audience Claim (aud)
     identify itself with a value in the audience claim.  If the principal
     processing the claim does not identify itself with a value in the
     "aud" claim when this claim is present, then the JWT MUST be
-    rejected.  In the general case, the "aud" value is an array of case-
-    sensitive strings, each containing a StringOrURI value.  In the
-    special case when the JWT has one audience, the "aud" value MAY be a
-    single case-sensitive string containing a StringOrURI value.  The
-    interpretation of audience values is generally application specific.
-    Use of this claim is OPTIONAL.
+    rejected.
+
+In the general case, the "aud" value is an array of case-
+sensitive strings, each containing a StringOrURI value.
+
+.. code-block:: python
+
+    payload = {
+        'some': 'payload',
+        'aud': ['urn:foo', 'urn:bar']
+    }
+
+    token = jwt.encode(payload, 'secret')
+    decoded = jwt.decode(token, 'secret', audience='urn:foo', algorithms=['HS256'])
+
+In the special case when the JWT has one audience, the "aud" value MAY be
+a single case-sensitive string containing a StringOrURI value.
 
 .. code-block:: python
 
@@ -200,6 +211,9 @@ Audience Claim (aud)
     token = jwt.encode(payload, 'secret')
     decoded = jwt.decode(token, 'secret', audience='urn:foo', algorithms=['HS256'])
 
+The interpretation of audience values is generally application specific.
+Use of this claim is OPTIONAL.
+
 If the audience claim is incorrect, `jwt.InvalidAudienceError` will be raised.
 
 Issued At Claim (iat)

From 46d19400ee327b713f8e39889285eb7feb3a7f72 Mon Sep 17 00:00:00 2001
From: Correy Lim <correylim@gmail.com>
Date: Fri, 24 Apr 2020 09:41:05 -0700
Subject: [PATCH 2/3] Add example of the `audience` param as an iterable

Demonstrate to users reading the documentation that the `audience`
parameter is not restricted to the `string` type, but can also accept an
iterable, as implemented in PR#306

https://github.com/jpadilla/pyjwt/pull/306
---
 docs/usage.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/usage.rst b/docs/usage.rst
index cdb84eb78..6db110087 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -211,6 +211,19 @@ a single case-sensitive string containing a StringOrURI value.
     token = jwt.encode(payload, 'secret')
     decoded = jwt.decode(token, 'secret', audience='urn:foo', algorithms=['HS256'])
 
+If multiple audiences are accepted, the ``audience`` parameter for
+``jwt.decode`` can also be an iterable
+
+.. code-block:: python
+
+    payload = {
+        'some': 'payload',
+        'aud': 'urn:foo'
+    }
+
+    token = jwt.encode(payload, 'secret')
+    decoded = jwt.decode(token, 'secret', audience=['urn:foo', 'urn:bar'], algorithms=['HS256'])
+
 The interpretation of audience values is generally application specific.
 Use of this claim is OPTIONAL.
 

From f01df865891a3fecad1e2f2578435a205726cf2a Mon Sep 17 00:00:00 2001
From: Correy Lim <correylim@gmail.com>
Date: Fri, 24 Apr 2020 09:44:42 -0700
Subject: [PATCH 3/3] Fix short title underlines

Short title underlines throw warnings in reStructuredText linters
---
 docs/usage.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/usage.rst b/docs/usage.rst
index 6db110087..fbd0ebb8e 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -2,7 +2,7 @@ Usage Examples
 ==============
 
 Encoding & Decoding Tokens with HS256
----------------------------------
+--------------------------------------
 
 .. code-block:: python
 
@@ -14,7 +14,7 @@ Encoding & Decoding Tokens with HS256
     {'some': 'payload'}
 
 Encoding & Decoding Tokens with RS256 (RSA)
----------------------------------
+-------------------------------------------
 
 .. code-block:: python