From 80beb70e9abd6b6116308465f12c0be2318a14b9 Mon Sep 17 00:00:00 2001
From: Andrew Svetlov <andrew.svetlov@gmail.com>
Date: Sun, 8 Nov 2015 10:47:19 +0800
Subject: [PATCH] Continue to work on documentation

---
 docs/glossary.rst  | 11 +++++++++++
 docs/index.rst     |  2 ++
 docs/reference.rst |  5 +----
 docs/usage.rst     | 33 ++++++++++++++++++++++++++++++++-
 4 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 174f3e4..6145d53 100644
--- a/docs/glossary.rst
+++ b/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.
diff --git a/docs/index.rst b/docs/index.rst
index a008f6c..a6dd724 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,7 +17,9 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   usage
    reference
+   examples
    glossary
 
 
diff --git a/docs/reference.rst b/docs/reference.rst
index d721cf3..db445dc 100644
--- a/docs/reference.rst
+++ b/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
-                      more complex object -- see used
-                      :class:`AbstractAuthorizationPolicy`
-                      implementation.
+   :param str permission: requested permission.
 
    :param context: additional object may be passed into
                    :meth:`AbstractAuthorizationPolicy.permission`
diff --git a/docs/usage.rst b/docs/usage.rst
index d4ef6c2..274ead7 100644
--- a/docs/usage.rst
+++ b/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.