Small updates in readme and docs (#125)

- add info about installation with extra ([]session])
- add links to examples
- move `Public api` header into related section

Author: gyermolenko

README.rst

@@ -9,17 +9,31 @@ aiohttp_security
 .. image:: https://img.shields.io/pypi/v/aiohttp-security.svg
     :target: https://pypi.python.org/pypi/aiohttp-security
 
-The library provides identity and autorization for `aiohttp.web`__.
+The library provides identity and authorization for `aiohttp.web`__.
 
 .. _aiohttp_web: http://aiohttp.readthedocs.org/en/latest/web.html
 
 __ aiohttp_web_
 
-Usage
------
-To install type ``pip install aiohttp_security``.
-Launch ``make doc`` and see examples or look under **demo** directory for a
-sample project.
+Installation
+------------
+Simplest case (authorization via cookies) ::
+
+    $ pip install aiohttp_security
+
+With `aiohttp-session` support ::
+
+    $ pip install aiohttp_security[session]
+
+Examples
+--------
+Take a look at examples:
+
+:ref:`aiohttp-security-example`
+
+:ref:`aiohttp-security-example-db-auth`
+
+and demos at **demo** directory.
 
 Documentation
 -------------

docs/index.rst

@@ -3,16 +3,9 @@ aiohttp_security
 
 The library provides security for :ref:`aiohttp.web<aiohttp-web>`.
 
-Usage
------
 
-
-License
--------
-
-``aiohttp_security`` is offered under the Apache 2 license.
-
-Contents:
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
@@ -23,7 +16,10 @@ Contents:
    example_db_auth
    glossary
 
+License
+-------
 
+``aiohttp_security`` is offered under the Apache 2 license.
 
 Indices and tables
 ==================

docs/usage.rst

@@ -13,6 +13,10 @@ First of all, what is *aiohttp_security* about?
 
 It is a set of public API functions and standard for implementation details.
 
+
+Public API
+==========
+
 API is implementation agnostic, all client code should not call policy
 code (see below) directly but use API only.
 
@@ -27,9 +31,6 @@ base classes for both concepts as well as several implementations
 shipped with the library. End user is free to build own implemetations
 if needed.
 
-Public API
-==========
-
 
 Authentication
 ==============
@@ -43,11 +44,6 @@ knowledge is there the user still registered in DB.
 If :class:`aiohttp.web.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.
+:term:`identity` is a string shared between browser and server.
 Thus it's not supposed to be database primary key, user login/email etc.
 Random string like uuid or hash is better choice.