Merge pull request #19 from crooksey/master

Started working on documentation

README.rst

@@ -1,38 +1,53 @@
 |Build Status| |Coverage Status| |PyPI|
 
-ziggurat_foundations
+Ziggurat Foundations
 =====================
 
-Framework agnostic set of sqlalchemy
-classes that make building applications that require permissions an easy task.
+**DOCUMENTATION**: http://readthedocs.org/docs/ziggurat-foundations/en/latest/
+
+**BUG TRACKER**: https://github.com/ergo/ziggurat_foundations
 
-ziggurat_foundations supplies a set of *sqlalchemy mixins* that can be used to extend
+Top layer to make authentication, resource ownership and permission management
+fast, simple and easy. In summary, Ziggurat Foundations (Zigg), is a set of framework agnostic 
+set of sqlalchemy classes, but most of the documentation refers to using it
+within pyramid. It is the perfect solution for handling complex login and user
+management systems, from e-commerce systems, to private intranets or large (and small)
+CMS systems.  It can easily be extended to support any additional features you may need (explained
+further in the documentation)
+
+Zigg has been used (at scale) for very large implementations (millions of real users) and
+has been extended for custom applications such as geo-location applications that rely
+on pin-point accuracy for a users location. Zigg has been designed to work for
+high end environments, where the user(s) are at the main focus of the application 
+(for example Zigg could become the backbone for a social media style application).
+
+Zigg supplies a set of *sqlalchemy mixins* that can be used to extend
 models in your application built in pyramid/flask/(your-favourite-framework-here).
 The aim of this project is to supply set of generic models that cover the most
 common needs in application development when it comes to authorization - using
-flat and tree like data structures.
-
+flat and tree like data structures. We provide nearly every feature you will need in
+a standard application, but provide the mixins as we understand that every implementation
+has its own use case and in doing so, extending the base models is very easy.
 
-**DOCUMENTATION**: http://readthedocs.org/docs/ziggurat-foundations/en/latest/
-
-**BUG TRACKER**: https://github.com/ergo/ziggurat_foundations
 
-So far following basics are supplied:
+Zigg supplies extendable, robust and well tested models that include:
 
 - User - base for user accounts
 - Group - container for many users
 - Resource - Arbitrary database entity that can represent various object hierarchies - blogs, forums, cms documents, pages etc.
 
-Currently following information and data manipulation is supported:
+Zigg provides standard functions that let you:
 
-- assigning arbitrary permissions directly to users (ie. access admin panel)
-- assigning users to groups
-- assigning arbitrary permissions to groups
-- assigning arbitrary resource permissions to users (ie. only user X can access  private forum)
-- assigning arbitrary resource permissions to groups
+- Assign arbitrary permissions directly to users (ie. access certain views)
+- Assign users to groups
+- Assign arbitrary permissions to groups
+- Assign arbitrary resource permissions to users (ie. only user X can access private forum)
+- Assign arbitrary resource permissions to groups
+- Assign a user o an external identity (such as facebook/twitter)
+- Manage the sign in/sign out process
+- Change users password and generate security codes
+- Example root factory for assiginging permissions per request
 
-The sqlalchemy mixins make all the interactions easy to use in your application
-and save development time.
 
 Ziggurat Foundations is BSD Licensed
 

docs/tutorial.rst → docs/configuration.rst

@@ -1,6 +1,6 @@
-========
-Tutorial
-========
+================================
+Configuring Ziggurat Foundations
+================================
 
 Installation and initial migration
 ==================================
@@ -9,15 +9,15 @@ Install the package:
 
 .. code-block:: bash
 
-    pip install ziggurat_foundations
+    $ pip install ziggurat_foundations
 
 Now it's time to initialize your model structure with alembic.
 
 You will first need to install alembic version **0.3.4** or above:
 
 .. code-block:: bash
 
-    pip install alembic>=0.3.4
+    $ pip install alembic>=0.3.4
 
 After you obtain recent alembic you can now run your migrations against
 database of your choice.
@@ -72,14 +72,16 @@ First you will need to create alembic.ini file with following contents:
     format = %(levelname)-5.5s [%(name)s] %(message)s
     datefmt = %H:%M:%S
 
-then you can run migration command::
+then you can run migration command:
 
-   alembic upgrade head
+.. code-block:: bash
+
+   $ alembic upgrade head
 
 At this point all your database structure should be prepared for usage.
 
-Using ziggurat_foundations within your application
-==================================================
+Implementing ziggurat_foundations within your application
+=========================================================
 
 .. warning::
 
@@ -89,7 +91,8 @@ Using ziggurat_foundations within your application
 We need to *include ALL mixins inside our application*
 and map classes together so internal methods can function properly.
 
-How to use the mixins inside your application:
+How to use the mixins inside your application, put the follwing code inside your models
+file to extend your existing models (if following the basic pyramid tutorial):
 
 .. code-block:: python
 
@@ -152,69 +155,6 @@ How to use the mixins inside your application:
     cryptacular compatible password manager to ziggurat_model_init, it will be used
     instead of creating default one.
 
-Usage examples
-==============
-
-Adding new user
----------------
-::
-
-    new_user = User()
-    DBSession.add(new_user)
-    ... populating new row ...
-    new_user.regenerate_security_code()
-    new_user.status = 1
-    new_user.set_password(new_password)
-
-
-Adding a resource that the user will own
-----------------------------------------
-::
-
-    resource = SomeResouce()
-    DBSession.add(resource)
-    user.resources.append(resource)
-
-Adding arbitrary user a 'view' permission to resource
------------------------------------------------------
-::
-
-    permission = UserResourcePermission(perm_name=perm_name,
-                                        user_id=user.user_id)
-    resource.user_permissions.append(permission)
-
-
-Checking permissions for users
-------------------------------
-
-Checking "resourceless" permission like "user can access admin panel::
-
-    request.user.permissions
-    for perm_user, perm_name in request.user.permissions:
-        print perm_user, perm_name
-
-Checking all permissions user has to specific resource::
-
-    resource = Resource.by_resource_id(rid)
-    for perm in resource.perms_for_user(user):
-        print perm.user, perm.perm_name, perm.type, perm.group, perm.resource, perm.owner
-        .... list acls ....
-
-Fetch all resources that user can "edit" or "vote"::
-
-    user.resources_with_perms(["edit","vote"])
-
-Connecting external identity like twitter login
------------------------------------------------
-::
-
-    ex_identity = ExternalIdentity()
-    ex_identity.external_id = XXX
-    ex_identity.external_user_name = XXX
-    ex_identity.provider_name = 'twitter.com'
-    ex_identity.access_token = XXX
-    ex_identity.token_secret = XXX
-    new_user.external_identities.append(ex_identity)
 
 
 Pyramid based examples of permission system building
@@ -223,7 +163,10 @@ Pyramid based examples of permission system building
 Example root context factory for pyramid to provide customizable permissions for specific views
 -----------------------------------------------------------------------------------------------
 
-This root factory can be used to allow only authenticated users to view::
+It is a good idea to keep the root factory inside your models file (if following the 
+basic pyramid tutorial). This root factory can be used to allow only authenticated users to view:
+
+.. code-block:: python
 
     class RootFactory(object):
         def __init__(self, request):
@@ -243,7 +186,9 @@ Example resource based pyramid context factory that can be used with url dispatc
 ---------------------------------------------------------------------------------
 
 This example shows how to protect and authorize users to perform actions on
-resources, you can configure your view to expect "edit" or "delete" permissions::
+resources, you can configure your view to expect "edit" or "delete" permissions:
+
+.. code-block:: python
 
     class ResourceFactory(object):
         def __init__(self, request):

docs/extensions/pyramid.rst

@@ -44,24 +44,36 @@ this will register 2 routes:
     * ziggurat_foundations.sign_in.sign_out_pattern = /custom_pattern
 
 It is also required to tell the extension where User model is located in your
-application for example::
+application for example in your ini file:
+
+.. code-block:: ini
 
     ziggurat_foundations.model_locations.User = yourapp.models:User
 
-Additional config options for extensions include:
+Additional config options for extensions include in your ini file:
+
+.. code-block:: ini
+
+    # name of POST key that will be used to supply user name
+    ziggurat_foundations.sign_in.username_key = username
+
+    # name of POST key that will be used to supply user password
+    ziggurat_foundations.sign_in.password_key = password
+
+    # name of POST key that will be used to provide additional value that can be used to redirect 
+    # user back to area that required authentication/authorization)
+    ziggurat_foundations.sign_in.came_from_key = came_from
+
+    # If you do not use a global DBSession variable, and you bundle DBSession insde the request
+    # you need to tell Zigg its naming convention, do this by providing a function that
+    # returns the correct request variable
+    ziggurat_foundations.session_provider_callable = yourapp.model:get_session_callable
+
 
-* **ziggurat_foundations.sign_in.username_key** = login *(name of POST key that will
-  be used to supply user name )*
-* **ziggurat_foundations.sign_in.password_key** = password *(name of POST key that
-  will be used to supply user password)*
-* **ziggurat_foundations.sign_in.came_from_key** = came_from *(name of POST key that
-  will be used to provide additional value that can be used to redirect user back
-  to area that required authentication/authorization)*
-* **ziggurat_foundations.session_provider_callable** = yourapp.model:get_session_callable
-  (the extension will use a callable `get_session_callable`  that expects a single argument `request` and is
-  supposed to return SQLAlchemy - handy for people who do not rely on ScopedSession but bind session to request object)
+Then for example inside your models (if you are using a db_session inse the request),
+you can do:
 
-Then for example inside your models (if you are using a db_session inse the request), you can do::
+.. code-block:: python
 
     def get_session_callable(request):
         return request.db_session

docs/index.rst

@@ -12,14 +12,19 @@ ziggurat_foundations
 .. image:: /_static/flask_small.png
    :alt: Flask Logo
 
-Framework agnostic set of sqlalchemy classes that make building applications 
-that require permissions (ACL's) an easy task.
+Top layer to make authentication, resource ownership and permission management
+fast, simple and easy. In summary, Ziggurat Foundations (Zigg), is a set of framework agnostic 
+set of sqlalchemy classes, but most of the documentation refers to using it
+within pyramid. It is the perfect solution for handling complex login and user
+management systems, from e-commerce systems, to private intranets or large (and small)
+CMS systems.  It can easily be extended to support any additional features you may need (explained
+further in the documentation)
 
 .. hint::
 
-    By default ziggurat_foundations expose some properties and functionalities that 
-    will make building apps with pyramid/flask/(your-favourite-framework-here) 
-    an easier task.   
+    Ziggurat Foundations aims to simplify user, permission and resource management,
+    allowing you to concentrate on application development, as opposed to developing
+    your own user and permission based models/code.   
 
 **DOCUMENTATION**: http://readthedocs.org/docs/ziggurat-foundations/en/latest/
 
@@ -30,11 +35,12 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   overview
-   tutorial
+   configuration
+   usage_examples
    extensions/pyramid
    api/index
 
+
    changelog