Fix tox "docs" environment to pass (jpadilla#567)

- Fixed doctest which included incorrect output.
- Use intersphinx to allow linking to Python JSONEncoder class.
- Fix param types after previous str/bytes cleanups.
- Fix param syntax to avoid vertical bar.

The command `tox -e docs` now passes.

Author: jdufresne

README.rst

@@ -42,7 +42,7 @@ Usage
     >>> import jwt
     >>> encoded = jwt.encode({"some": "payload"}, "secret", algorithm="HS256")
     >>> print(encoded)
-    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzb21lIjoicGF5bG9hZCJ9.4twFt5NiznN84AWoo1d7KO1T_yoc0Z6XOpOVswacPZg
+    eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U
     >>> jwt.decode(encoded, "secret", algorithms=["HS256"])
     {'some': 'payload'}
 

docs/api.rst

@@ -23,7 +23,7 @@ API Reference
 
     Verify the ``jwt`` token signature and return the token claims.
 
-    :param str|bytes jwt: the token to be decoded
+    :param str jwt: the token to be decoded
     :param str key: the key suitable for the allowed algorithm
 
     :param list algorithms: allowed algorithms, e.g. ``["ES256"]``
@@ -43,9 +43,9 @@ API Reference
         * ``verify_iss=False`` check that ``iss`` (issuer) claim matches ``issuer``
         * ``verify_signature=True`` verify the JWT cryptographic signature
 
-    :param iterable audience: optional, the value for ``verify_aud`` check
+    :param 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 float leeway: a time margin in seconds for the expiration check
     :rtype: dict
     :returns: the JWT claims
 

docs/conf.py

@@ -83,6 +83,10 @@ def find_version(*file_paths):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# Intersphinx extension.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
 
 # -- Options for HTML output ----------------------------------------------
 

docs/index.rst

@@ -32,7 +32,7 @@ Example Usage
     >>> import jwt
     >>> encoded_jwt = jwt.encode({"some": "payload"}, "secret", algorithm="HS256")
     >>> print(encoded_jwt)
-    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzb21lIjoicGF5bG9hZCJ9.4twFt5NiznN84AWoo1d7KO1T_yoc0Z6XOpOVswacPZg
+    eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzb21lIjoicGF5bG9hZCJ9.Joh1R2dYzkRvDkqv3sygm5YyK8Gi4ShZqbhK2gxcs2U
     >>> jwt.decode(encoded_jwt, "secret", algorithms=["HS256"])
     {'some': 'payload'}