Continue to work on documentation

docs/glossary.rst

@@ -25,6 +25,17 @@
 
       https://pypi.python.org/pypi/asyncio/
 
+   authentication
+
+      Actions related to retrieving, storing and removing user's
+      :term:`identity`.
+
+      Authenticated user has no access rights, the system even has no
+      knowledge is there the user still registered in DB.
+
+      If :term:`request` has an :term:`identity` it means the user has
+      some ID that should be checked by :term:`authorization` policy.
+
    identity
 
       Session-wide :class:`str` for identifying user.

docs/index.rst

@@ -17,7 +17,9 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   usage
    reference
+   examples
    glossary
 
 

docs/reference.rst

@@ -78,10 +78,7 @@ Public API functions
 
    :param request: :class:`aiohttp.web.Request` object.
 
-   :param permission: requested permission. May be :class:`str` or
+   :param str permission: requested permission.
-                      more complex object -- see used
-                      :class:`AbstractAuthorizationPolicy`
-                      implementation.
 
    :param context: additional object may be passed into
                    :meth:`AbstractAuthorizationPolicy.permission`

docs/usage.rst

@@ -1,4 +1,35 @@
+.. _aiohttp-security-usage:
+
+
+=======
+ Usage
+=======
+
+.. currentmodule:: aiohttp_security
+.. highlight:: python
+
+The library is build on top of two policies: :term:`authentication`
+and :term:`authorization`.
+
+
+Authentication
+==============
+
+Actions related to retrieving, storing and removing user's
+:term:`identity`.
+
+Authenticated user has no access rights, the system even has no
+knowledge is there the user still registered in DB.
+
+If :term:`request` has an :term:`identity` it means the user has
+some ID that should be checked by :term:`authorization` policy.
+
+
+
+
+
+
 identity is a string shared between browser and server.
-Thus it should not be database primary key etc.
+Thus it's not supposed to be database primary key, user login/email etc.
 Random string like uuid or hash is better choice.