Update docs for 1.2

README.md

@@ -7,9 +7,9 @@
 
 [![Build Status](https://travis-ci.org/ahopkins/sanic-jwt.svg?branch=master)](https://travis-ci.org/ahopkins/sanic-jwt)
 [![Documentation](https://readthedocs.org/projects/sanic-jwt/badge/?version=latest)](http://sanic-jwt.readthedocs.io/en/latest/?badge=latest)
-[![Waffle.io](https://badge.waffle.io/ahopkins/sanic-jwt.svg?columns=In%20Progress)](https://waffle.io/ahopkins/sanic-jwt)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/9727756ffccd45f7bc5ad6292596e03d)](https://www.codacy.com/app/ahopkins/sanic-jwt?utm_source=github.com&utm_medium=referral&utm_content=ahopkins/sanic-jwt&utm_campaign=Badge_Grade)
 [![Test Coverage](https://codecov.io/gh/ahopkins/sanic-jwt/branch/dev/graph/badge.svg)](https://codecov.io/gh/ahopkins/sanic-jwt)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 
 Sanic JWT adds authentication protection and endpoints to [Sanic].

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==1.8.1
+sphinx_rtd_theme==0.4.2

docs/source/index.rst

@@ -3,7 +3,7 @@ Sanic JWT
 =========
 
 |Latest PyPI version| |Version status| |Python versions| |Build Status|
-|Codacy Badge| |Documentation| Waffle.io|
+|Codacy Badge| |Documentation| |Black|
 
 
 Sanic JWT adds authentication protection and endpoints to `Sanic <http://sanic.readthedocs.io>`_.
@@ -38,6 +38,14 @@ Pick your favorite user management system, run :doc:`a single class to initializ
 
 ------------
 
++++++++++++++++++++++++++++
+What is new in Version 1.2?
++++++++++++++++++++++++++++
+
+**Version 1.2** saw a a few `minor fixes and changes <https://github.com/ahopkins/sanic-jwt/issues?q=is%3Aopen+is%3Aissue+milestone%3Av1.2>`_. Some new features were added to allow custom claims and additional payload verifications. **Version 1.1.4** is still stable, so there is no need to upgrade to **1.2**.
+
+In addition, there was a change that will (unfortunately) have some potential impact on users. Expired and invalid tokens will report as ``HTTP 401``.
+
 +++++++++++++++++++++++++++
 What is new in Version 1.1?
 +++++++++++++++++++++++++++
@@ -105,5 +113,5 @@ Have fun, and happy coding.
    :target: https://www.codacy.com/app/ahopkins/sanic-jwt?utm_source=github.com&utm_medium=referral&utm_content=ahopkins/sanic-jwt&utm_campaign=Badge_Grade
 .. |Documentation| image:: https://readthedocs.org/projects/sanic-jwt/badge/?version=latest
    :target: http://sanic-jwt.readthedocs.io/en/latest/?badge=latest
-.. |Waffle.io| image:: https://badge.waffle.io/ahopkins/sanic-jwt.svg?columns=In%20Progress
-   :target: https://waffle.io/ahopkins/sanic-jwt
+.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/ambv/black

docs/source/pages/configuration.rst

@@ -275,9 +275,9 @@ Alias for ``cookie_access_token_name``
 | **Default**: ``False``
 |
 
----------
+-----------------
 ``do_protection``
----------
+-----------------
 
 | **Purpose**: Whether or not protection should be inforced. This almost **always** should stay as ``True``, unless you know what you are doing since it will effectively render the ``@protected`` decorator useless and all traffic will be passed thru.
 | **Default**: ``True``

docs/source/pages/initialization.rst

@@ -357,6 +357,7 @@ One of the most powerful concepts of the JWT is that you are able to pass data (
         authenticate=lambda: True,
         extend_payload=my_extender)
 
+------------
 
 ---------------------
 Runtime Configuration
@@ -375,6 +376,8 @@ There are several ways to :doc:`configure the settings<configuration>` for Sanic
         claim_iat=True,
         cookie_domain='example.com',)
 
+------------
+
 ----------------
 Additional Views
 ----------------
@@ -433,6 +436,8 @@ As an example, perhaps you would like to create a "passwordless" login. You coul
         async def options(self, request):
             return response.text('', status=204)
 
+------------
+
 -------------------
 Component Overrides
 -------------------

docs/source/pages/payload.rst

@@ -96,6 +96,59 @@ Not before - ``NBF``
 
 ------------
 
++++++++++++++
+Custom Claims
++++++++++++++
+
+Sometimes you may find a need to add claims to a JWT beyond what is built into Sanic JWT.
+
+To do so, simply subclass ``Claim`` and register them at :doc:`initialization<initialization>` by providing the custom claim class in a list to ``custom_claims``.
+
+.. code-block:: python
+
+    from sanic_jwt import Claim, Initialize
+
+    MyCustomClaim(Claim):
+        key = 'foo'
+
+        def setup(self, payload, user):
+            return 'bar'
+
+        def verify(self, value):
+            return value == 'bar'
+
+    Initialize(..., custom_claims=[MyCustomClaim])
+
+There are three attributes that a ``Claim`` must have: ``key``, ``setup``, and ``verify``.
+
+| ``key``: The name of the claim and the key that will be inserted into the payload.
+| ``setup``: A method to be run at the time the payload is created. It should return the value of the claim.
+| ``verify``: A method to be run when a token is being verified. It should return a ``boolean`` whether or not the claim has been met.
+|
+
+------------
+
++++++++++++++++++++
+Extra Verifications
++++++++++++++++++++
+
+Besides registering custom claims, sometimes you may find the need to do additional verifications on a payload. For example, perhaps you want to run checks that span more than one claim on the payload.
+
+To accomplish this, you can register a list of methods (that each return a ``boolean``) at :doc:`initialization<initialization>` by providing the list to ``extra_verifications``.
+
+.. code-block:: python
+
+    def check_number_of_claims(payload):
+        return len(payload.keys()) == 5
+
+    extra_verifications = [check_number_of_claims]
+    Initialize(
+        ...,
+        extra_verifications=extra_verifications
+    )
+
+------------
+
 ++++++++++++++++
 Payload Handlers
 ++++++++++++++++