split docs into pages

18 files changed, 368 insertions, 306 deletions

diff --git a/docs/Makefile b/docs/Makefile
index df66c3e..5128596 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -4,7 +4,6 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = ItsDangerous
 SOURCEDIR     = .
 BUILDDIR      = _build
 
diff --git a/docs/_static/itsdangerous-logo-sidebar.png b/docs/_static/itsdangerous-logo-sidebar.png
new file mode 100644
index 0000000..807c350
--- /dev/null
+++ b/docs/_static/itsdangerous-logo-sidebar.png
diff --git a/docs/changes.rst b/docs/changes.rst
new file mode 100644
index 0000000..955deaf
--- /dev/null
+++ b/docs/changes.rst
@@ -0,0 +1,4 @@
+Changes
+=======
+
+.. include:: ../CHANGES.rst
diff --git a/docs/conf.py b/docs/conf.py
index ae04141..88f36bb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -27,12 +27,15 @@ html_context = {
         ProjectLink("Issue Tracker", "https://github.com/pallets/itsdangerous/issues/"),
     ]
 }
-html_sidebars = {"index": ["project.html", "localtoc.html", "versions.html"]}
+html_sidebars = {
+    "index": ["project.html", "localtoc.html", "searchbox.html"],
+    "**": ["localtoc.html", "relations.html", "searchbox.html"],
+}
+singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]}
 html_static_path = ["_static"]
+html_logo = "_static/itsdangerous-logo-sidebar.png"
 html_title = "It's Dangerous Documentation ({})".format(version)
 html_show_sourcelink = False
-html_domain_indices = False
-html_experimental_html5_writer = True
 
 # LaTeX ----------------------------------------------------------------
 
diff --git a/docs/encoding.rst b/docs/encoding.rst
new file mode 100644
index 0000000..0c5a0e3
--- /dev/null
+++ b/docs/encoding.rst
@@ -0,0 +1,8 @@
+.. module:: itsdangerous.encoding
+
+Encoding Utilities
+==================
+
+.. autofunction:: base64_encode
+
+.. autofunction:: base64_decode
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 0000000..0d75655
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,22 @@
+.. module:: itsdangerous.exc
+
+Exceptions
+==========
+
+.. autoexception:: BadData
+    :members:
+
+.. autoexception:: BadSignature
+    :members:
+
+.. autoexception:: BadTimeSignature
+    :members:
+
+.. autoexception:: SignatureExpired
+    :members:
+
+.. autoexception:: BadHeader
+    :members:
+
+.. autoexception:: BadPayload
+    :members:
diff --git a/docs/index.rst b/docs/index.rst
index 91af156..6db655a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,5 +1,3 @@
-.. module:: itsdangerous
-
 .. rst-class:: hide-header
 
 It's Dangerous
@@ -24,292 +22,45 @@ The initial implementation was inspired by `Django's signing module
 <https://docs.djangoproject.com/en/dev/topics/signing/>`_. It also
 supports JSON Web Signatures (JWS). The library is BSD licensed.
 
-Installation
-------------
-
-You can get the library directly from PyPI::
-
-    pip install itsdangerous
-
-Example Use Cases
------------------
-
--   You can serialize and sign a user ID for unsubscribing of newsletters
-    into URLs.  This way you don't need to generate one-time tokens and
-    store them in the database.  Same thing with any kind of activation
-    link for accounts and similar things.
--   Signed objects can be stored in cookies or other untrusted sources
-    which means you don't need to have sessions stored on the server, which
-    reduces the number of necessary database queries.
--   Signed information can safely do a roundtrip between server and client
-    in general which makes them useful for passing server-side state to a
-    client and then back.
-
-Signing Interface
------------------
-
-The most basic interface is the signing interface.  The :class:`Signer` class
-can be used to attach a signature to a specific string:
-
->>> from itsdangerous import Signer
->>> s = Signer('secret-key')
->>> s.sign('my string')
-'my string.wh6tMHxLgJqB6oY1uT73iMlyrOA'
-
-The signature is appended to the string, separated by a dot (``.``).  To
-validate the string, use the :meth:`~Signer.unsign` method:
-
->>> s.unsign('my string.wh6tMHxLgJqB6oY1uT73iMlyrOA')
-'my string'
-
-If unicode strings are provided, an implicit encoding to utf-8 happens.
-However after unsigning you won't be able to tell if it was unicode or
-a bytestring.
-
-If the unsigning fails you will get an exception:
-
->>> s.unsign('my string.wh6tMHxLgJqB6oY1uT73iMlyrOX')
-Traceback (most recent call last):
-  ...
-itsdangerous.BadSignature: Signature "wh6tMHxLgJqB6oY1uT73iMlyrOX" does not match
-
-Signatures with Timestamps
---------------------------
-
-If you want to expire signatures you can use the :class:`TimestampSigner`
-class which will additionally put in a timestamp information and sign it.
-On unsigning you can validate that the timestamp did not expire:
-
->>> from itsdangerous import TimestampSigner
->>> s = TimestampSigner('secret-key')
->>> string = s.sign('foo')
->>> s.unsign(string, max_age=5)
-Traceback (most recent call last):
-  ...
-itsdangerous.SignatureExpired: Signature age 15 > 5 seconds
-
-Serialization
--------------
-
-Because strings are hard to handle this module also provides a
-serialization interface similar to json/pickle and others.  (Internally
-it uses simplejson by default, however this can be changed by subclassing.)
-The :class:`Serializer` class implements that:
-
->>> from itsdangerous import Serializer
->>> s = Serializer('secret-key')
->>> s.dumps([1, 2, 3, 4])
-'[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo'
-
-And it can of course also load:
-
->>> s.loads('[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo')
-[1, 2, 3, 4]
-
-If you want to have the timestamp attached you can use the
-:class:`TimedSerializer`.
-
-URL Safe Serialization
-----------------------
-
-Often it is helpful if you can pass these trusted strings to environments
-where you only have a limited set of characters available.  Because of
-this, itsdangerous also provides URL safe serializers:
-
->>> from itsdangerous import URLSafeSerializer
->>> s = URLSafeSerializer('secret-key')
->>> s.dumps([1, 2, 3, 4])
-'WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo'
->>> s.loads('WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo')
-[1, 2, 3, 4]
-
-JSON Web Signatures
--------------------
-
-Starting with “itsdangerous” 0.18 JSON Web Signatures are also supported.
-They generally work very similar to the already existing URL safe
-serializer but will emit headers according to the current draft (10) of
-the JSON Web Signature (JWS) [``draft-ietf-jose-json-web-signature``].
-
->>> from itsdangerous import JSONWebSignatureSerializer
->>> s = JSONWebSignatureSerializer('secret-key')
->>> s.dumps({'x': 42})
-'eyJhbGciOiJIUzI1NiJ9.eyJ4Ijo0Mn0.ZdTn1YyGz9Yx5B5wNpWRL221G1WpVE5fPCPKNuc6UAo'
-
-When loading the value back the header will not be returned by default
-like with the other serializers.  However it is possible to also ask for
-the header by passing ``return_header=True``.
-Custom header fields can be provided upon serialization:
-
->>> s.dumps(0, header_fields={'v': 1})
-'eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM'
->>> s.loads('eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAf'
-...         'TLn82_iIQD70J_j-3F4z_aM', return_header=True)
-...
-(0, {u'alg': u'HS256', u'v': 1})
-
-“itsdangerous” only provides HMAC SHA derivatives and the none algorithm
-at the moment and does not support the ECC based ones.  The algorithm in
-the header is checked against the one of the serializer and on a mismatch
-a :exc:`BadSignature` exception is raised.
-
-.. _the-salt:
 
-The Salt
---------
+Installing
+----------
 
-All classes also accept a salt argument.  The name might be misleading
-because usually if you think of salts in cryptography you would expect the
-salt to be something that is stored alongside the resulting signed string
-as a way to prevent rainbow table lookups.  Such salts are usually public.
+Install and update using `pip`_:
 
-In “itsdangerous”, like in the original Django implementation, the salt
-serves a different purpose.  You could describe it as namespacing.  It's
-still not critical if you disclose it because without the secret key it
-does not help an attacker.
+.. code-block:: text
 
-Let's assume that you have two links you want to sign.  You have the
-activation link on your system which can activate a user account and then
-you have an upgrade link that can upgrade a user's account to a paid
-account which you send out via email.  If in both cases all you sign is
-the user ID a user could reuse the variable part in the URL from the
-activation link to upgrade the account.  Now you could either put more
-information in there which you sign (like the intention: upgrade or
-activate), but you could also use different salts:
+    pip install -U ItsDangerous
 
->>> s1 = URLSafeSerializer('secret-key', salt='activate-salt')
->>> s1.dumps(42)
-'NDI.kubVFOOugP5PAIfEqLJbXQbfTxs'
->>> s2 = URLSafeSerializer('secret-key', salt='upgrade-salt')
->>> s2.dumps(42)
-'NDI.7lx-N1P-z2veJ7nT1_2bnTkjGTE'
->>> s2.loads(s1.dumps(42))
-Traceback (most recent call last):
-  ...
-itsdangerous.BadSignature: Signature "kubVFOOugP5PAIfEqLJbXQbfTxs" does not match
+.. _pip: https://pip.pypa.io/en/stable/quickstart/
 
-Only the serializer with the same salt can load the value:
 
->>> s2.loads(s2.dumps(42))
-42
-
-Responding to Failure
----------------------
-
-Starting with itsdangerous 0.14 exceptions have helpful attributes which
-allow you to inspect payload if the signature check failed.  This has to
-be done with extra care because at that point you know that someone
-tampered with your data but it might be useful for debugging purposes.
-
-Example usage::
-
-    from itsdangerous import URLSafeSerializer, BadSignature, BadData
-    s = URLSafeSerializer('secret-key')
-    decoded_payload = None
-    try:
-        decoded_payload = s.loads(data)
-        # This payload is decoded and safe
-    except BadSignature, e:
-        encoded_payload = e.payload
-        if encoded_payload is not None:
-            try:
-                decoded_payload = s.load_payload(encoded_payload)
-            except BadData:
-                pass
-            # This payload is decoded but unsafe because someone
-            # tampered with the signature.  The decode (load_payload)
-            # step is explicit because it might be unsafe to unserialize
-            # the payload (think pickle instead of json!)
-
-If you don't want to inspect attributes to figure out what exactly went
-wrong you can also use the unsafe loading::
-
-    from itsdangerous import URLSafeSerializer
-    s = URLSafeSerializer('secret-key')
-    sig_okay, payload = s.loads_unsafe(data)
-
-The first item in the returned tuple is a boolean that indicates if the
-signature was correct.
-
-Python 3 Notes
---------------
-
-On Python 3 the interface that itsdangerous provides can be confusing at
-first.  Depending on the internal serializer it wraps the return value of
-the functions can alter between unicode strings or bytes objects.  The
-internal signer is always byte based.
-
-This is done to allow the module to operate on different serializers
-independent of how they are implemented.  The module decides on the
-type of the serializer by doing a test serialization of an empty object.
-
-API
----
-
-Signers
-~~~~~~~
-
-.. autoclass:: Signer
-   :members:
-
-.. autoclass:: TimestampSigner
-   :members:
-
-Signing Algorithms
-~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: NoneAlgorithm
-
-.. autoclass:: HMACAlgorithm
-
-Serializers
-~~~~~~~~~~~
-
-.. autoclass:: Serializer
-   :members:
-
-.. autoclass:: TimedSerializer
-   :members:
-
-.. autoclass:: JSONWebSignatureSerializer
-   :members:
-
-.. autoclass:: TimedJSONWebSignatureSerializer
-   :members:
-
-.. autoclass:: URLSafeSerializer
-
-.. autoclass:: URLSafeTimedSerializer
-
-Exceptions
-~~~~~~~~~~
-
-.. autoexception:: BadData
-   :members:
-
-.. autoexception:: BadSignature
-   :members:
-
-.. autoexception:: BadTimeSignature
-   :members:
-
-.. autoexception:: SignatureExpired
-   :members:
-
-.. autoexception:: BadHeader
-   :members:
-
-.. autoexception:: BadPayload
-   :members:
-
-Useful Helpers
-~~~~~~~~~~~~~~
+Example Use Cases
+-----------------
 
-.. autofunction:: base64_encode
+-   You can serialize and sign a user ID in a URL and email it to them
+    to unsubscribe from a newsletter. This way you don't need to
+    generate one-time tokens and store them in the database. Same thing
+    with any kind of activation link for accounts and similar things.
+-   Signed objects can be stored in cookies or other untrusted sources
+    which means you don't need to have sessions stored on the server,
+    which reduces the number of necessary database queries.
+-   Signed information can safely do a roundtrip between server and
+    client in general which makes them useful for passing server-side
+    state to a client and then back.
 
-.. autofunction:: base64_decode
 
-Changelog
-=========
+Table of Contents
+-----------------
 
-.. include:: ../CHANGES.rst
+.. toctree::
+
+    signer
+    serializer
+    exceptions
+    timed
+    url_safe
+    jws
+    encoding
+    license
+    changes
diff --git a/docs/jws.rst b/docs/jws.rst
new file mode 100644
index 0000000..da12253
--- /dev/null
+++ b/docs/jws.rst
@@ -0,0 +1,42 @@
+.. module:: itsdangerous.jws
+
+JSON Web Signature (JWS)
+========================
+
+JSON Web Signatures (JWS) work similarly to the existing URL safe
+serializer but will emit headers according to `draft-ietf-jose-json-web
+-signature <http://self-issued.info/docs/draft-ietf-jose-json-web
+-signature.html>`_.
+
+.. code-block:: python
+
+    from itsdangerous import JSONWebSignatureSerializer
+    s = JSONWebSignatureSerializer("secret-key")
+    s.dumps({"x": 42})
+    'eyJhbGciOiJIUzI1NiJ9.eyJ4Ijo0Mn0.ZdTn1YyGz9Yx5B5wNpWRL221G1WpVE5fPCPKNuc6UAo'
+
+When loading the value back the header will not be returned by default
+like with the other serializers. However it is possible to also ask for
+the header by passing ``return_header=True``. Custom header fields can
+be provided upon serialization:
+
+.. code-block:: python
+
+    s.dumps(0, header_fields={"v": 1})
+    'eyJhbGciOiJIUzI1NiIsInYiOjF9.MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM'
+    s.loads(
+        "eyJhbGciOiJIUzI1NiIsInYiOjF9"
+        ".MA.wT-RZI9YU06R919VBdAfTLn82_iIQD70J_j-3F4z_aM"
+    )
+    (0, {'alg': 'HS256', 'v': 1})
+
+itsdangerous only provides HMAC SHA derivatives and the none algorithm
+at the moment and does not support the ECC based ones. The algorithm in
+the header is checked against the one of the serializer and on a
+mismatch a :exc:`~itsdangerous.exc.BadSignature` exception is raised.
+
+.. autoclass:: JSONWebSignatureSerializer
+    :members:
+
+.. autoclass:: TimedJSONWebSignatureSerializer
+    :members:
diff --git a/docs/license.rst b/docs/license.rst
new file mode 100644
index 0000000..cc8c2f3
--- /dev/null
+++ b/docs/license.rst
@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../LICENSE.rst
diff --git a/docs/make.bat b/docs/make.bat
index aa05f1d..7893348 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -9,7 +9,6 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=.
 set BUILDDIR=_build
-set SPHINXPROJ=ItsDangerous
 
 if "%1" == "" goto help
 
diff --git a/docs/serializer.rst b/docs/serializer.rst
new file mode 100644
index 0000000..1b1da66
--- /dev/null
+++ b/docs/serializer.rst
@@ -0,0 +1,134 @@
+.. module:: itsdangerous.serializer
+
+Serialization Interface
+=======================
+
+The :doc:`/signer` only signs strings. To sign other types, the
+:class:`Serializer` class provides a ``dumps``/``loads`` interface
+similar to Python's :mod:`json` module, which serializes the object to a
+string then signs that.
+
+Use :meth:`~Serializer.dumps` to serialize and sign the data:
+
+.. code-block:: python
+
+    from itsdangerous.serializer import Serializer
+    s = Serializer("secret-key")
+    s.dumps([1, 2, 3, 4])
+    b'[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo'
+
+Use :meth:`~Serializer.loads` to verify the signature and deserialize
+the data.
+
+.. code-block:: python
+
+    s.loads('[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo')
+    [1, 2, 3, 4]
+
+By default, data is serialized to JSON. If simplejson is installed, it
+is preferred over the built-in :mod:`json` module. This internal
+serializer can be changed by subclassing.
+
+To record and validate the age of the signature, see :doc:`/timed`.
+To serialize to a format that is safe to use in URLs, see
+:doc:`/url_safe`.
+
+
+.. _the-salt:
+
+The Salt
+--------
+
+All classes also accept a salt argument. The name might be misleading
+because usually if you think of salts in cryptography you would expect
+the salt to be something that is stored alongside the resulting signed
+string as a way to prevent rainbow table lookups. Such salts are usually
+public.
+
+In itsdangerous, like in the original Django implementation, the salt
+serves a different purpose. You could describe it as namespacing. It's
+still not critical if you disclose it because without the secret key it
+does not help an attacker.
+
+Let's assume that you have two links you want to sign. You have the
+activation link on your system which can activate a user account and you
+have an upgrade link that can upgrade a user's account to a paid account
+which you send out via email. If in both cases all you sign is the user
+ID a user could reuse the variable part in the URL from the activation
+link to upgrade the account. Now you could either put more information
+in there which you sign (like the intention: upgrade or activate), but
+you could also use different salts:
+
+.. code-block:: python
+
+    from itsdangerous.url_safe import URLSafeSerializer
+    s1 = URLSafeSerializer("secret-key", salt="activate")
+    s1.dumps(42)
+    'NDI.MHQqszw6Wc81wOBQszCrEE_RlzY'
+    s2 = URLSafeSerializer("secret-key", salt="upgrade")
+    s2.dumps(42)
+    'NDI.c0MpsD6gzpilOAeUPra3NShPXsE'
+
+The second serializer can't load data dumped with the first because the
+salts differ:
+
+.. code-block:: python
+
+    s2.loads(s1.dumps(42))
+    Traceback (most recent call last):
+      ...
+    itsdangerous.exc.BadSignature: Signature "MHQqszw6Wc81wOBQszCrEE_RlzY" does not match
+
+Only the serializer with the same salt can load the data:
+
+.. code-block:: python
+
+    s2.loads(s2.dumps(42))
+    42
+
+
+Responding to Failure
+---------------------
+
+Exceptions have helpful attributes which allow you to inspect the
+payload if the signature check failed. This has to be done with extra
+care because at that point you know that someone tampered with your data
+but it might be useful for debugging purposes.
+
+.. code-block:: python
+
+    from itsdangerous.serializer import Serializer
+    from itsdangerous.exc import BadSignature, BadData
+
+    s = URLSafeSerializer("secret-key")
+    decoded_payload = None
+
+    try:
+        decoded_payload = s.loads(data)
+        # This payload is decoded and safe
+    except BadSignature as e:
+        if e.payload is not None:
+            try:
+                decoded_payload = s.load_payload(e.payload)
+            except BadData:
+                pass
+            # This payload is decoded but unsafe because someone
+            # tampered with the signature. The decode (load_payload)
+            # step is explicit because it might be unsafe to unserialize
+            # the payload (think pickle instead of json!)
+
+If you don't want to inspect attributes to figure out what exactly went
+wrong you can also use :meth:`~Serializer.loads_unsafe`:
+
+.. code-block:: python
+
+    sig_okay, payload = s.loads_unsafe(data)
+
+The first item in the returned tuple is a boolean that indicates if the
+signature was correct.
+
+API
+---
+
+.. autoclass:: Serializer
+    :members:
diff --git a/docs/signer.rst b/docs/signer.rst
new file mode 100644
index 0000000..b25efb9
--- /dev/null
+++ b/docs/signer.rst
@@ -0,0 +1,49 @@
+.. module:: itsdangerous.signer
+
+Signing Interface
+=================
+
+The most basic interface is the signing interface. The :class:`Signer`
+class can be used to attach a signature to a specific string:
+
+.. code-block:: python
+
+    from itsdangerous import Signer
+    s = Signer("secret-key")
+    s.sign("my string")
+    b'my string.wh6tMHxLgJqB6oY1uT73iMlyrOA'
+
+The signature is appended to the string, separated by a dot. To validate
+the string, use the :meth:`~Signer.unsign` method:
+
+.. code-block:: python
+
+    s.unsign(b"my string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
+    b'my string'
+
+If unicode strings are provided, an implicit encoding to UTF-8 happens.
+However after unsigning you won't be able to tell if it was unicode or
+a bytestring.
+
+If the value is changed, the signature will no longer match, and
+unsigning will raise a :exc:`~itsdangerous.exc.BadSignature` exception:
+
+.. code-block:: python
+
+    s.unsign(b"different string.wh6tMHxLgJqB6oY1uT73iMlyrOA")
+    Traceback (most recent call last):
+      ...
+    itsdangerous.exc.BadSignature: Signature "wh6tMHxLgJqB6oY1uT73iMlyrOA" does not match
+
+To record and validate the age of a signature, see :doc:`/timed`.
+
+.. autoclass:: Signer
+    :members:
+
+
+Signing Algorithms
+------------------
+
+.. autoclass:: NoneAlgorithm
+
+.. autoclass:: HMACAlgorithm
diff --git a/docs/timed.rst b/docs/timed.rst
new file mode 100644
index 0000000..8964d17
--- /dev/null
+++ b/docs/timed.rst
@@ -0,0 +1,28 @@
+.. module:: itsdangerous.timed
+
+Signing With Timestamps
+=======================
+
+If you want to expire signatures you can use the
+:class:`TimestampSigner` class which will adds timestamp information and
+signs it. On unsigning you can validate that the timestamp did not
+expire:
+
+.. code-block:: python
+
+    from itsdangerous import TimestampSigner
+    s = TimestampSigner('secret-key')
+    string = s.sign('foo')
+
+.. code-block:: python
+
+    s.unsign(string, max_age=5)
+    Traceback (most recent call last):
+      ...
+    itsdangerous.exc.SignatureExpired: Signature age 15 > 5 seconds
+
+.. autoclass:: TimestampSigner
+    :members:
+
+.. autoclass:: TimedSerializer
+    :members:
diff --git a/docs/url_safe.rst b/docs/url_safe.rst
new file mode 100644
index 0000000..f3a00ee
--- /dev/null
+++ b/docs/url_safe.rst
@@ -0,0 +1,21 @@
+.. module:: itsdangerous.url_safe
+
+URL Safe Serialization
+======================
+
+Often it is helpful if you can pass these trusted strings in places
+where you only have a limited set of characters available. Because of
+this, itsdangerous also provides URL safe serializers:
+
+.. code-block:: python
+
+    from itsdangerous.url_safe import URLSafeSerializer
+    s = URLSafeSerializer("secret-key")
+    s.dumps([1, 2, 3, 4])
+    'WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo'
+    s.loads("WzEsMiwzLDRd.wSPHqC0gR7VUqivlSukJ0IeTDgo")
+    [1, 2, 3, 4]
+
+.. autoclass:: URLSafeSerializer
+
+.. autoclass:: URLSafeTimedSerializer
diff --git a/src/itsdangerous/jws.py b/src/itsdangerous/jws.py
index deb3ab4..b1f31de 100644
--- a/src/itsdangerous/jws.py
+++ b/src/itsdangerous/jws.py
@@ -127,7 +127,7 @@ class JSONWebSignatureSerializer(Serializer):
         return header
 
     def dumps(self, obj, salt=None, header_fields=None):
-        """Like :meth:`~Serializer.dumps` but creates a JSON Web
+        """Like :meth:`.Serializer.dumps` but creates a JSON Web
         Signature. It also allows for specifying additional fields to be
         included in the JWS header.
         """
diff --git a/src/itsdangerous/serializer.py b/src/itsdangerous/serializer.py
index a2d4795..1e764d5 100644
--- a/src/itsdangerous/serializer.py
+++ b/src/itsdangerous/serializer.py
@@ -24,17 +24,17 @@ class Serializer(object):
     it's not available.
 
     You do not need to subclass this class in order to switch out or
-    customize the :class:`Signer`. You can instead also pass a different
+    customize the :class:`.Signer`. You can instead pass a different
     class to the constructor as well as keyword arguments as a dict that
-    should be forwarded
+    should be forwarded.
 
-    .. code-block:: python
+    .. code-block:: python3
 
         s = Serializer(signer_kwargs={'key_derivation': 'hmac'})
 
     .. versionchanged:: 0.14:
-        The `signer` and `signer_kwargs` parameters were added to the
-        constructor.
+        The ``signer`` and ``signer_kwargs`` parameters were added to
+        the constructor.
     """
 
     #: If a serializer module or class is not passed to the constructor
@@ -70,7 +70,7 @@ class Serializer(object):
 
     def load_payload(self, payload, serializer=None):
         """Loads the encoded object. This function raises
-        :class:`BadPayload` if the payload is not valid. The
+        :class:`.BadPayload` if the payload is not valid. The
         ``serializer`` parameter can be used to override the serializer
         stored on the class. The encoded ``payload`` should always be
         bytes.
@@ -100,7 +100,7 @@ class Serializer(object):
 
     def make_signer(self, salt=None):
         """Creates a new instance of the signer to be used. The default
-        implementation uses the :class:`Signer` base class.
+        implementation uses the :class:`.Signer` base class.
         """
         if salt is None:
             salt = self.salt
@@ -124,7 +124,7 @@ class Serializer(object):
         f.write(self.dumps(obj, salt))
 
     def loads(self, s, salt=None):
-        """Reverse of :meth:`dumps`. Raises :exc:`BadSignature` if the
+        """Reverse of :meth:`dumps`. Raises :exc:`.BadSignature` if the
         signature validation fails.
         """
         s = want_bytes(s)
diff --git a/src/itsdangerous/timed.py b/src/itsdangerous/timed.py
index 49e308f..3599a7e 100644
--- a/src/itsdangerous/timed.py
+++ b/src/itsdangerous/timed.py
@@ -15,11 +15,10 @@ from .signer import Signer
 
 
 class TimestampSigner(Signer):
-    """Works like the regular :class:`Signer` but also records the time
+    """Works like the regular :class:`.Signer` but also records the time
     of the signing and can be used to expire signatures. The
-    :meth:`unsign` method can raise :exc:`SignatureExpired` if the
-    unsigning failed because the signature is expired. This exception is
-    a subclass of :exc:`BadSignature`.
+    :meth:`unsign` method can raise :exc:`.SignatureExpired` if the
+    unsigning failed because the signature is expired.
     """
 
     def get_timestamp(self):
@@ -43,7 +42,7 @@ class TimestampSigner(Signer):
         return value + sep + self.get_signature(value)
 
     def unsign(self, value, max_age=None, return_timestamp=False):
-        """Works like the regular :meth:`~Signer.unsign` but can also
+        """Works like the regular :meth:`.Signer.unsign` but can also
         validate the time. See the base docstring of the class for
         the general behavior. If ``return_timestamp`` is ``True`` the
         timestamp of the signature will be returned as a naive
@@ -111,18 +110,17 @@ class TimestampSigner(Signer):
 
 class TimedSerializer(Serializer):
     """Uses :class:`TimestampSigner` instead of the default
-    :class:`Signer`.
+    :class:`.Signer`.
     """
 
     default_signer = TimestampSigner
 
     def loads(self, s, max_age=None, return_timestamp=False, salt=None):
-        """Reverse of :meth:`dumps`, raises :exc:`BadSignature` if the
+        """Reverse of :meth:`dumps`, raises :exc:`.BadSignature` if the
         signature validation fails. If a ``max_age`` is provided it will
         ensure the signature is not older than that time in seconds. In
-        case the signature is outdated, :exc:`SignatureExpired` is
-        raised, which is a subclass of :exc:`BadSignature`. All
-        arguments are forwarded to the signer's
+        case the signature is outdated, :exc:`.SignatureExpired` is
+        raised. All arguments are forwarded to the signer's
         :meth:`~TimestampSigner.unsign` method.
         """
         base64d, timestamp = self.make_signer(salt).unsign(
diff --git a/src/itsdangerous/url_safe.py b/src/itsdangerous/url_safe.py
index 8e7aa78..fcaa011 100644
--- a/src/itsdangerous/url_safe.py
+++ b/src/itsdangerous/url_safe.py
@@ -52,14 +52,14 @@ class URLSafeSerializerMixin(object):
 
 
 class URLSafeSerializer(URLSafeSerializerMixin, Serializer):
-    """Works like :class:`Serializer` but dumps and loads into a URL
+    """Works like :class:`.Serializer` but dumps and loads into a URL
     safe string consisting of the upper and lowercase character of the
     alphabet as well as ``'_'``, ``'-'`` and ``'.'``.
     """
 
 
 class URLSafeTimedSerializer(URLSafeSerializerMixin, TimedSerializer):
-    """Works like :class:`TimedSerializer` but dumps and loads into a
+    """Works like :class:`.TimedSerializer` but dumps and loads into a
     URL safe string consisting of the upper and lowercase character of
     the alphabet as well as ``'_'``, ``'-'`` and ``'.'``.
     """