Initial custom grant type documentation.

Improved Grant Type section to let developers create or implement their own custom grant type. Or also help them implementing new RFC.

4 files changed, 84 insertions, 11 deletions

diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst
new file mode 100644
index 0000000..ba5446c
--- /dev/null
+++ b/docs/oauth2/grants/custom_grant.rst
@@ -0,0 +1,49 @@
+Custom Grant type
+-----------------
+
+Writing a custom grant type can be useful to implement a specification
+which is in an early draft, or implement a grant provided by a
+specific OAuth2.0 Authorization Server documentation but not provided
+by oauthlib. For information, any grant types with a clear
+specification can be integrated in oauthlib, just make a PR for that
+!. See :doc:`how to contribute here </contributing>`.
+
+Please find below an example of how to create a new grant and use it
+in an endpoint:
+
+.. contents:: Tutorial Contents
+    :depth: 3
+
+
+1. Define your Grant Type
+-------------------------
+
+The heart of your code is done by subclassing
+:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.GrantTypeBase`.
+If you want to use it in the Authorize endpoint, you will have to
+implement `create_authorization_response`, if in the Token endpoint,
+implement `create_token_response`.
+
+
+2. Associate it with Endpoints
+------------------------------
+Then, once declared, you have to create an instance of your grant and
+add it to your
+endpoint. I.e. :py:class:`oauthlib.oauth2.rfc6749.endpoints.AuthorizationEndpoint`
+or :py:class:`oauthlib.oauth2.rfc6749.endpoints.TokenEndpoint`. You
+can see concrete examples in
+:py:class:`oauthlib.oauth2.rfc6749.endpoints.pre_configured.Server`
+for examples.
+
+3. Example
+----------
+
+To be completed.
+
+.. code-block:: python
+    class XXXZZZGrant(GrantTypeBase):
+        def create_token_response(self, request, token_handler):
+            if not request.grant_type == 'xxx_zzz':
+                raise errors.UnsupportedGrantTypeError(request=request)
+            ...
+         
diff --git a/docs/oauth2/grants/custom_validators.rst b/docs/oauth2/grants/custom_validators.rst
index 4629e6f..9917dd7 100644
--- a/docs/oauth2/grants/custom_validators.rst
+++ b/docs/oauth2/grants/custom_validators.rst
@@ -1,5 +1,15 @@
 Custom Validators
 -----------------
 
-.. autoclass:: oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer
+The Custom validators are useful when you want to change a particular
+behavior of an existing grant. That is often needed because of the
+diversity of the identity softwares and to let the oauthlib framework to be
+flexible as possible.
+
+However, if you are looking into writing a custom grant type, please
+refer to the :doc:`Custom Grant Type </oauth2/grants/custom_grant>`
+instead.
+
+.. autoclass::
+               oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer
     :members:
diff --git a/docs/oauth2/grants/grants.rst b/docs/oauth2/grants/grants.rst
index 16b17be..d2d9dcc 100644
--- a/docs/oauth2/grants/grants.rst
+++ b/docs/oauth2/grants/grants.rst
@@ -9,23 +9,30 @@ Grant types
     implicit
     password
     credentials
-    custom_validators
+    refresh
     jwt
+    custom_validators
+    custom_grant
 
-Grant types are what make OAuth 2 so flexible. The Authorization Code grant is
-very similar to OAuth 1 (with less crypto), the Implicit grant serves less
-secure applications such as mobile applications, the Resource Owner Password
-Credentials grant allows for legacy applications to incrementally transition to
-OAuth 2, the Client Credentials grant is excellent for embedded services and
-backend applications.
+Grant types are what make OAuth 2 so flexible. The :doc:`Authorization
+Code grant </oauth2/grants/authcode>` is the default for almost all
+Web Applications, the :doc:`Implicit grant </oauth2/grants/implicit>`
+serves less secure applications such as Mobile Applications or
+Single-Page Applications, the :doc:`Client Credentials grant
+</oauth2/grants/credentials>` is excellent for embedded services and
+backend applications. We have also the :doc:`Resource Owner Password
+Credentials grant </oauth2/grants/password>` for legacy applications
+to incrementally transition to OAuth 2.
 
 The main purpose of the grant types is to authorize access to protected
 resources in various ways with different security credentials.
 
 Naturally, OAuth 2 allows for extension grant types to be defined and OAuthLib
-attempts to cater for easy inclusion of this as much as possible.
+attempts to cater for easy inclusion of this as much as possible. See
+:doc:`Custom Grant Type </oauth2/grants/custom_grant>`.
 
-OAuthlib also offers hooks for registering your own custom validations for use
+OAuthlib also offers hooks for registering your own :doc:`Custom
+Validators </oauth2/grants/custom_validators>` for use
 with the existing grant type handlers
 (:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.ValidatorsContainer`).
 In some situations, this may be more convenient than subclassing or writing
@@ -36,6 +43,7 @@ client to request new tokens for as long as you as provider allow them too. In
 general, OAuth 2 tokens should expire quickly and rather than annoying the user
 by require them to go through the authorization redirect loop you may use the
 refresh token to get a new access token. Refresh tokens, contrary to what their
-name suggest, are components of a grant type rather than token types (like
+name suggest, are components of a grant type (see :doc:`Refresh Token
+grant </oauth2/grants/refresh>`) rather than token types (like
 Bearer tokens), much like the authorization code in the authorization code
 grant.
diff --git a/docs/oauth2/grants/refresh.rst b/docs/oauth2/grants/refresh.rst
new file mode 100644
index 0000000..df925ff
--- /dev/null
+++ b/docs/oauth2/grants/refresh.rst
@@ -0,0 +1,6 @@
+Refresh Token Grant
+------------------------
+
+.. autoclass:: oauthlib.oauth2.RefreshTokenGrant
+    :members:
+    :inherited-members: