docs: minimal application example

Reviewed-by: Tibor Simko <tibor.simko@cern.ch>
Signed-off-by: Jiri Kuncar <jiri.kuncar@cern.ch>

AUTHORS

@@ -1,5 +1,5 @@
 Authors
--------
+=======
 
 Flask-SSO is developed for use in `Invenio <http://invenio-software.org>`_
 digital library software.

CHANGES

@@ -5,7 +5,7 @@ Here you can see the full list of changes between each Flask-SSO
 release.
 
 Version 0.2.0 (released 2014-06-26)
------------------------------------
+
 - Allowing ';' separator in HTTP data.
 - Fix for dictionary key order in tests.
 - Fix for Python 3.3 string comparison.
@@ -14,5 +14,5 @@ Version 0.2.0 (released 2014-06-26)
 - New configuration option SSO_LOGIN_ENDPOINT.
 
 Version 0.1
------------
-- Initial public release
+
+- Initial public release.

CONTRIBUTING.rst

@@ -0,0 +1,30 @@
+Contributing
+============
+
+Bug reports, feature requests, and other contributions are welcome.
+If you find a demonstrable problem that is caused by the code of this
+library, please:
+
+1. Search for `already reported problems
+   <https://github.com/inveniosoftware/flask-sso/issues>`_.
+2. Check if the issue has been fixed or is still reproducible on the
+   latest `master` branch.
+3. Create an issue with **a test case**.
+
+If you create a feature branch, you can run the tests to ensure everything is
+operating correctly:
+
+.. code-block:: console
+
+    $ ./run-tests.sh
+    ...
+    Ran 8 tests in 0.246s
+
+    OK
+    Name                 Stmts   Miss  Cover   Missing
+    --------------------------------------------------
+    flask_sso/__init__      47      0   100%
+    flask_sso/config         4      0   100%
+    flask_sso/version        2      0   100%
+    --------------------------------------------------
+    TOTAL                   53      0   100%

MANIFEST.in

@@ -7,7 +7,7 @@
 ## it under the terms of the Revised BSD License; see LICENSE file for
 ## more details.
 
-include LICENSE AUTHORS CHANGES README.rst
+include LICENSE AUTHORS CHANGES CONTRIBUTING.rst README.rst
 include .coveragerc run-tests.sh
 include docs/*.rst docs/*.py docs/Makefile
 include tests/*.py

docs/conf.py

@@ -104,14 +104,15 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme_path = ['_themes']
-html_theme = 'flask'
+html_theme = 'flask_small'
 
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-    'index_logo_height': '0'
+    'index_logo': False,
+    'index_logo_height': '40px;'
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -136,7 +137,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/index.rst

@@ -1,52 +1,162 @@
 ===========
  Flask-SSO
 ===========
+.. currentmodule:: flask_sso
 
-Flask-SSO
-=========
 
-.. image:: https://travis-ci.org/inveniosoftware/flask-sso.png?branch=master
-    :target: https://travis-ci.org/inveniosoftware/flask-sso
-.. image:: https://coveralls.io/repos/inveniosoftware/flask-sso/badge.png?branch=master
-    :target: https://coveralls.io/r/inveniosoftware/flask-sso
+.. raw:: html
+
+    <p style="height:22px; margin:0 0 0 2em; float:right">
+        <a href="https://travis-ci.org/inveniosoftware/flask-sso">
+            <img src="https://travis-ci.org/inveniosoftware/flask-sso.png?branch=master"
+                 alt="travis-ci badge"/>
+        </a>
+        <a href="https://coveralls.io/r/inveniosoftware/flask-sso">
+            <img src="https://coveralls.io/repos/inveniosoftware/flask-sso/badge.png?branch=master"
+                 alt="coveralls.io badge"/>
+        </a>
+    </p>
+
 
 Flask-SSO is a Flask extension permitting to set up Shibboleth
 Single-Sign-On authentication in Flask based web applications.
 
-User's Guide
+Contents
+--------
+
+.. contents::
+   :local:
+   :backlinks: none
+
+
+Installation
 ============
 
+Flask-SSO is on PyPI so all you need is :
+
+.. code-block:: console
+
+    $ pip install flask-sso
+
+The development version can be downloaded from `its page at GitHub
+<http://github.com/inveniosoftware/flask-sso>`_.
+
+.. code-block:: console
+
+    $ git clone https://github.com/inveniosoftware/flask-sso.git
+    $ cd flask-sso
+    $ python setup.py develop
+    $ ./run-tests.sh
+
+Requirements
+^^^^^^^^^^^^
+
+Flask-SSO has the following dependencies:
+
+* `Flask <https://pypi.python.org/pypi/Flask>`_
+* `blinker <https://pypi.python.org/pypi/blinker>`_
+* `six <https://pypi.python.org/pypi/six>`_
+
+Flask-SSO requires Python version 2.6, 2.7 or 3.3+
+
+
+Quickstart
+==========
+
 This part of the documentation will show you how to get started in using
 Flask-SSO with Flask.
 
-.. toctree::
-   :maxdepth: 2
+This guide assumes you have successfully installed Flask-SSO and a working
+understanding of Flask. If not, follow the installation steps and read about
+Flask at http://flask.pocoo.org/docs/.
+
+
+A Minimal Example
+^^^^^^^^^^^^^^^^^
+
+A minimal Flask-SSO usage example looks like this.
+
+First, let's create the application and initialise the extension:
 
-   installation
-   quickstart
-   userguide
+.. code-block:: python
 
+    from flask import Flask, session, redirect
+    from flask_sso import SSO
+    app = Flask("myapp")
+    ext = SSO(app=app)
 
-API Reference
+
+Second, let's configure the attribute map for converting environment
+variables to a dictionary containing user information:
+
+.. code-block:: python
+
+    #: Default attribute map
+    SSO_ATTRIBUTE_MAP = {
+        'ADFS_AUTHLEVEL': (False, 'authlevel'),
+        'ADFS_GROUP': (True, 'group'),
+        'ADFS_LOGIN': (True, 'nickname'),
+        'ADFS_ROLE': (False, 'role'),
+        'ADFS_EMAIL': (True, 'email'),
+        'ADFS_IDENTITYCLASS': (False, 'external'),
+        'HTTP_SHIB_AUTHENTICATION_METHOD': (False, 'authmethod'),
+    }
+
+    app.config.setdefault('SSO_ATTRIBUTE_MAP', SSO_ATTRIBUTE_MAP)
+
+
+Third, let's set up a login handler function that reads user information
+and stores it for later usage:
+
+.. code-block:: python
+
+    @sso.login_handler
+    def login_callback(user_info):
+        """Store information in session."""
+        session["user"] = user_info
+
+
+Fourth, we can now greet the user using his SSO login name:
+
+.. code-block:: python
+
+    @app.route("/")
+    def index():
+        """Display user information or force login."""
+        if "user" in session:
+            return "Welcome {name}".format(name=session["user"]["nickname"])
+        return redirect(app.config["SSO_LOGIN_URL"])
+
+
+Configuration
 =============
 
-If you are looking for information on a specific function, class or
-method, this part of the documentation is for you.
+.. automodule:: flask_sso.config
+
+
+API
+===
+
+This documentation section is automatically generated from Flask-SSO's
+source code.
+
+Flask-SSO
+^^^^^^^^^
+
+.. automodule:: flask_sso
+
+.. autoclass:: SSO
+   :members:
 
-.. toctree::
-   :maxdepth: 2
 
-   api
+.. include:: ../CHANGES
 
+.. include:: ../CONTRIBUTING.rst
 
-Additional Notes
-================
 
-Notes on how to contribute, legal information and changelog are here for the interested.
+License
+=======
 
-.. toctree::
-   :maxdepth: 2
+.. include:: ../LICENSE
 
-   contributing
-   changelog
-   license
+.. include:: ../AUTHORS