Document top-level .encode and .decode to close #459 (#482)

Co-authored-by: José Padilla <jpadilla@webapplicate.com>

2 files changed, 64 insertions, 4 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 08b6991..3f66173 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -3,7 +3,67 @@ API Reference
 
 .. module:: jwt
 
-TODO: Document PyJWS / PyJWT classes
+.. function:: encode(payload, key, algorithm="HS256", headers=None, json_encoder=None)
+
+    Encode the ``payload`` as JSON Web Token.
+
+    :param dict payload: JWT claims, e.g. ``dict(iss=..., aud=..., sub=...)``
+    :param str key: a key suitable for the chosen algorithm:
+
+        * for **asymmetric algorithms**: PEM-formatted private key, a multiline string
+        * for **symmetric algorithms**: plain string, sufficiently long for security
+
+    :param str algorithm: algorithm to sign the token with, e.g. ``"ES256"``
+    :param dict headers: additional JWT header fields, e.g. ``dict(kid="my-key-id")``
+    :param json.JSONEncoder json_encoder: custom JSON encoder for ``payload`` and ``headers``
+    :rtype: str
+    :returns: a JSON Web Token
+
+.. function:: decode(jwt, key="", verify=True, algorithms=None, options=None, audience=None, issuer=None, leeway=0, verify_expiration=True)
+
+    Verify the ``jwt`` token signature and return the token claims.
+
+    :param str|bytes jwt: the token to be decoded
+    :param str key: the key suitable for the allowed algorithm
+    :param bool verify: whether to verify the JWT signature, on by default
+
+        .. deprecated:: 1.5.1
+           to disable signature validation, use ``options=(verify_signature=False)``
+
+    :param list algorithms: allowed algorithms, e.g. ``["ES256"]``
+
+        .. note:: It is highly recommended to specify the expected ``algorithms``.
+
+        .. note:: It is insecure to mix symmetric and asymmetric algorithms because they require different kinds of keys.
+
+    :param dict options: extended decoding and validation options
+
+        * ``require_exp=False`` check that ``exp`` (expiration) claim is present
+        * ``require_iat=False`` check that ``iat`` (issued at) claim is present
+        * ``require_nbf=False`` check that ``nbf`` (not before) claim is present
+        * ``verify_aud=False`` check that ``aud`` (audience) claim matches ``audience``
+        * ``verify_iat=False`` check that ``iat`` (issued at) claim value is an integer
+        * ``verify_exp=False`` check that ``exp`` (expiration) claim value is OK
+        * ``verify_iss=False`` check that ``iss`` (issuer) claim matches ``issuer``
+        * ``verify_signature=True`` verify the JWT cryptographic signature
+        * ``verify_expiration``
+
+            .. deprecated:: 1.2.0
+                Use ``verify_exp`` instead
+
+
+    :param str|iterable audience: optional, the value for ``verify_aud`` check
+    :param str issuer: optional, the value for ``verify_iss`` check
+    :param int|float leeway: a time margin in seconds for the expiration check
+    :param bool verify_expiration:
+
+        .. deprecated:: 1.2.0
+            Use ``options=(verify_exp=...)`` instead
+
+    :rtype: dict
+    :returns: the JWT claims
+
+.. note:: TODO: Document PyJWS / PyJWT classes
 
 Exceptions
 ----------
diff --git a/docs/usage.rst b/docs/usage.rst
index fbd0ebb..d2da71a 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -2,7 +2,7 @@ Usage Examples
 ==============
 
 Encoding & Decoding Tokens with HS256
---------------------------------------
+-------------------------------------
 
 .. code-block:: python
 
@@ -27,7 +27,7 @@ Encoding & Decoding Tokens with RS256 (RSA)
     {'some': 'payload'}
 
 Specifying Additional Headers
----------------------------------
+-----------------------------
 
 .. code-block:: python
 
@@ -36,7 +36,7 @@ Specifying Additional Headers
 
 
 Reading the Claimset without Validation
------------------------------------------
+---------------------------------------
 
 If you wish to read the claimset of a JWT without performing validation of the
 signature or any of the registered claim names, you can set the ``verify``