Update docs.

docs/index.rst

@@ -26,7 +26,7 @@ Contents:
    sections/relyingparties
    sections/serverkeys
    sections/templates
-   sections/claims
+   sections/scopesclaims
    sections/userconsent
    sections/oauth2
    sections/settings

docs/sections/scopesclaims.rst

@@ -1,7 +1,7 @@
-.. _claims:
+.. _scopesclaims:
 
-Standard Claims
-###############
+Scopes and Claims
+#################
 
 This subset of OpenID Connect defines a set of standard Claims. They are returned in the UserInfo Response.
 
@@ -41,8 +41,8 @@ List of all the ``claims`` keys grouped by scopes:
 | updated_at         |                |                       |                        |
 +--------------------+----------------+-----------------------+------------------------+
 
-How to populate userinfo response
-=================================
+How to populate standard claims
+===============================
 
 Somewhere in your Django ``settings.py``::
 
@@ -65,3 +65,48 @@ Now test an Authorization Request using these scopes ``openid profile email`` an
 
 .. note::
     Please **DO NOT** add extra keys or delete the existing ones in the ``claims`` dict. If you want to add extra claims to some scopes you can use the ``OIDC_EXTRA_SCOPE_CLAIMS`` setting.
+
+How to add custom scopes and claims
+===================================
+
+The ``OIDC_EXTRA_SCOPE_CLAIMS`` setting is used to add extra scopes specific for your app. Is just a class that inherit from ``oidc_provider.lib.claims.ScopeClaims``. You can create or modify scopes by adding this methods into it:
+
+* ``info_scopename`` class property for setting the verbose name and description.
+* ``scope_scopename`` method for returning some information related.
+
+Let's say that you want add your custom ``foo`` scope for your OAuth2/OpenID provider. So when a client (RP) makes an Authorization Request containing ``foo`` in the list of scopes, it will be listed in the consent page (``templates/oidc_provider/authorize.html``) and then some specific claims like ``bar`` will be returned from the ``/userinfo`` response.
+
+Somewhere in your Django ``settings.py``::
+
+    OIDC_USERINFO = 'yourproject.oidc_provider_settings.CustomScopeClaims'
+
+Inside your oidc_provider_settings.py file add the following class::
+
+    from django.utils.translation import ugettext as _
+    from oidc_provider.lib.claims import ScopeClaims
+
+    class CustomScopeClaims(ScopeClaims):
+
+        info_foo = (
+            _(u'Foo'),
+            _(u'Some description for the scope.'),
+        )
+
+        def scope_foo(self):
+            # self.user - Django user instance.
+            # self.userinfo - Dict returned by OIDC_USERINFO function.
+            # self.scopes - List of scopes requested.
+            dic = {
+                'bar': 'Something dynamic here',
+            }
+
+            return dic
+
+        # If you want to change the description of the profile scope, you can redefine it.
+        info_profile = (
+            _(u'Profile'),
+            _(u'Another description.'),
+        )
+
+.. note::
+    If a field is empty or ``None`` inside the dictionary your return on ``scope_scopename`` method, it will be cleaned from the response.

docs/sections/settings.rst

@@ -48,49 +48,10 @@ OIDC_EXTRA_SCOPE_CLAIMS
 
 OPTIONAL. ``str``. A string with the location of your class. Default is ``oidc_provider.lib.claims.ScopeClaims``.
 
-Used to add extra scopes specific for your app. This class MUST inherit ``ScopeClaims``.
+Used to add extra scopes specific for your app. OpenID Connect RP's will use scope values to specify what access privileges are being requested for Access Tokens.
 
-OpenID Connect Clients will use scope values to specify what access privileges are being requested for Access Tokens.
+Read more about how to implement it in :ref:`scopesclaims` section.
 
-`Here <http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims>`_ you have the standard scopes defined by the protocol.
-
-You can create or modify scopes using:
-
-* ``info_scopename`` class property for setting the verbose name and description.
-* ``scope_scopename`` method for returning some information related.
-
-Check out an example of how to implement it::
-
-    from django.utils.translation import ugettext as _
-    from oidc_provider.lib.claims import ScopeClaims
-
-    class MyAppScopeClaims(ScopeClaims):
-
-        info_books = (
-            _(u'Books'), # Verbose name of the scope.
-            _(u'Access to your books.'), # Description of the scope.
-        )
-
-        def scope_books(self):
-            # Here, for example, you can search books for this user.
-            # self.user - Django user instance.
-            # self.userinfo - Instance of your custom OIDC_USERINFO class.
-            # self.scopes - List of scopes requested.
-
-            dic = {
-                'books_readed': books_readed_count,
-            }
-
-            return dic
-
-        # If you want to change the description of the profile scope, you can redefine it.
-        info_profile = (
-            _(u'Profile'),
-            _(u'Another description.'),
-        )
-
-.. note::
-    If a field is empty or ``None`` inside the dictionary your return on ``scope_scopename`` method, it will be cleaned from the response.
 
 OIDC_IDTOKEN_EXPIRE
 ===================