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.