Docs: some more doc pages

docs/index.txt

@@ -4,8 +4,8 @@
 Welcome to django-authority's documentation!
 ============================================
 
-django-authority is a layer between Django's basic permission system (provided
-through ``django.contrib.auth`` and your application:
+django-authority is a powerful layer between Django's basic permission system
+(provided through ``django.contrib.auth``) and your application:
 
 .. image:: .static/authority-scheme-layer.png
 
@@ -14,13 +14,17 @@ Summarized this application provides three abilities:
 1. It gives you the ability to add permissions like Django's generic permissions
    to any kind of model without storing them in the model's META attribute.
 
-2. It provides a very simple way to create per-object-permissions. (Also known
-   as row level permissions)
-
+2. It provides a very simple way to create per-object-permissions. You might
+   be more familiar with the term *row level permissions*.
+   
 3. It wraps Django's generic permissions so you can use the same syntax as
    for the above ones. But note that django-authority does not add any
    voodoo-code to Django's ``contrib.auth`` system so your existing permission
    system keeps intact!
+
+.. warning:: We have just started with the documentation and it's far from
+   being perfect. If you found glitches, errors or just have feedback, please
+   contact the team: :ref:`team_and_support`.
    
 Documentation
 =============
@@ -33,25 +37,19 @@ Documentation
    installation
    configuration
 
-**Creating permissions:**
+**Create and check permissions:**
 
 .. toctree::
    :maxdepth: 1
    
    permission_create_basic
-   permission_create_your_own
-   permission_create_key_lock
+   permission_create_per_object
+   permission_create_custom
    permission_admin_handling
-   
-**Checking permissions:**
 
-.. toctree::
-   :maxdepth: 1
+.. note:: The create-permission topics are based on each other. If you are new
+   to django-authority we encourage to read from top to bottom.
    
-   permission_check_in_views
-   permission_check_using_the_decorator
-   permission_check_in_templates
-
 Other pages
 ===========
 

docs/permission_admin_handling.txt

@@ -3,3 +3,20 @@
 ===================================================
 Handling permissions using Django's admin interface
 ===================================================
+
+Using python-code
+-----------------
+
+*to be written*
+
+
+Using Django's admin interface
+------------------------------
+
+The more easy way to add per-object permissions is to use Django's admin
+interface.
+
+Using templatetags
+------------------
+
+*to be written*

docs/permission_check_decorator.txt

@@ -0,0 +1,5 @@
+.. _permission_check_decorator::
+
+=====================================
+Check permissions using the decorator
+=====================================

docs/permission_check_in_templates.txt

@@ -1,5 +0,0 @@
-.. _permission_check_in_templates:
-
-==================================
-Check for permissions in templates
-==================================

docs/permission_create_basic.txt

@@ -4,11 +4,111 @@
 Create a basic permission
 =========================
 
+Where to store permissions?
+===========================
+
+First of all: All following permission classes should be placed in a file
+called ``permissions.py`` in your application or project-directory. For the 
+*why* please have a look on `How permissions are discovered`_.
+
+A basic permission
+==================
+
+Let's start with a example::
+
+    import authority
+    from authority import permissions
+    from django.contrib.flatpages.models import Flatpage
+
+    class FlatpagePermission(permissions.BasePermission):
+        label = 'flatpage_permission'
+
+    authority.register(Flatpage, FlatpagePermission)
+
+Let's make the code clear. First of, if you want to create a new permission
+you have to subclass it from the BasePermission class::
+
+    from authority import permissions
+    class FlatpagePermission(permissions.BasePermission):
+        # ...
+
+Next you need to name this permission using the ``label`` attribute::
+
+    class FlatpagePermission(permissions.BasePermission):
+        label = 'flatpage_permission'
+
+And finally you need to register the permission to the pool of all other
+permissions::
+
+    authority.register(Flatpage, FlatpagePermission)
+
+The syntax of this is simple::
+
+    authority.register(<model>, <permissionclass>)
+
+While this is not much code, you already wrapped Django's basic permissions
+(add_flatpage, change_flatpage, delete_flatpage) for the model ``Flatpage``
+and you are ready to use it within your templates or code:
+
+.. note:: See `Django's basic permissions`_ how Django creates this permissions for you.
+
+.. _Django's basic permissions: http://docs.djangoproject.com/en/dev/topics/auth/#permissions
+
+
+Example permission checks
+=========================
+
+This section shows you how to check for Django's basic permissions with
+django-authorit
+
+In your python code
+-------------------
+::
+
+    def my_view(request):    
+        check = FlatPagePermission(request.user)
+        if check.change_flatpage():
+            print "Yay, you can change a flatpage!"
+
+Using the view decorator
+------------------------
+::
+
+    from authority.decorators import permission_required_or_403
+
+    @permission_required_or_403('flatpage_permission.change_flatpage')
+    def my_view(request):
+        # ...
+        
+See :ref:`permission_check_decorator` how the decorator works in detail.
+        
+In your templates
+-----------------
+::
+
+    {% ifhasperm "flatpage_permission.change_flatpage" request.user %}
+        Yay, you can change a flatpage!
+    {% else %}
+        Nope, sorry. You aren't allowed to change a flatpage.
+    {% endifhasperm %}
+
+See :ref:`permission_check_in_templates` how the templatetag works in detail.
 
 How permissions are discovered
 ==============================
 
+On first runtime of your project ``authority.autodiscover()`` will load all
+``permission.py`` files that are in your ``settings.INSTALLED_APPS``
+applications. See :ref:`configuration` how to set up ``autodiscover``.
+
 .. image:: .static/authority-permission-py.png
    :align: left
+   
+We encourage you to place your permission-classes in a file called
+``permission.py`` inside your project or application directory. Not only that
+this behaviour will keep your application structure clean, if you use
+``authority.autodiscover()`` it's guaranteed that every permission-class is
+loaded at runtime.
 
-lala
+If you really want, you can place these permission-classes in other files
+that are loaded at runtime. ``__init__.py`` or ``models.py`` are such files.

docs/permission_create_custom.txt

@@ -0,0 +1,7 @@
+.. _permission_create_custom:
+
+==========================
+Create a custom permission
+==========================
+
+django-authority allows you to define 

docs/permission_create_per_object.txt

@@ -0,0 +1,117 @@
+.. _permission_create_per_object:
+
+==============================
+Create a per-object permission
+==============================
+
+django-authority provides a super simple but nifty feature called *per-object
+permission*. A description would be::
+
+    Attach a <codename> to an object
+    Attach a <codename> to an user
+    
+    If the user has <codename> and the object has <codename> then do-something,
+    otherwise do-something-else.
+
+This might sound strange but let's have a deeper look on this. In terms of
+users and flatpages a visual example would be:
+
+.. image:: .static/authority-object-1to1.png
+
+*The user is allowed to review the flatpage Events.*
+
+You are not limited to a 1:1 relation, you can add this ``codename`` to
+multiple objects:
+
+.. image:: .static/authority-object-1toN.png
+
+*The user is allowed to review the flatpages Events and Contact.*
+
+And you can do this with any objects in any direction:
+
+.. image:: .static/authority-object-NtoN.png
+
+*The user is allowed to review the flatpages Events and Contact. Another user
+is allowed to publish the fltapage Events.*
+
+Create per-object permissions
+=============================
+
+Creating per-object permissions is super simple. See this piece of permission
+class code::
+    
+    class FlatPagePermission(BasePermission):
+        label = 'flatpage_permission'
+        checks = ('review',)
+
+    authority.register(FlatPage, FlatPagePermission)
+
+This permission class is similar to the one we already created in
+:ref:`permission_create_basic` but we added the line::
+
+    checks = ('review',)
+
+This tells the permission class that it has a permission check (or ``codename``)
+``review``. Under the hood this check gets translated to ``review_flatpage``
+(``review_<modelname>``).
+
+.. important:: Be sure that you have understand that we have not written any line
+   of code yet. We just added the ``codename`` to the checks attribute.
+
+Attach per-object permissions to objects
+========================================
+
+Please see :ref:`permission_admin_handling` for this.
+
+Check per-object permissions
+============================
+
+As we noted above, we have not written any permission-comparing code yet. This
+is your work. In theory the permission lookup for per-object permissions is::
+
+    if <theuser> has <codename> and <object> has <codename>:
+        return True
+    else:
+        return False
+
+The syntax is similiar to the permission-checks we have already
+seen in :ref:`permission_create_basic` for the basic permissions but now we
+have to give each function an ``obj`` argument containing the model-instance
+we want to check!
+
+In your python code
+-------------------
+::
+
+    from myapp.permissions import FlatPagePermission
+    def my_view(request):    
+        check = FlatPagePermission(request.user)
+        flatpage_object = Flatpage.objects.get(url='/homepage/')
+        if check.review_flatpage(obj=flatpage_object):
+            print "Yay, you can change *this* flatpage!"
+
+Using the view decorator
+------------------------
+::
+
+    from django.contrib.auth import Flatpage
+    from authority.decorators import permission_required_or_403
+
+    @permission_required_or_403('flatpage_permission.review_flatpage',
+                                (Flatpage, 'url__iexact', 'url')) # The flatpage_object
+    def my_view(request, url):
+        # ...
+        
+See :ref:`permission_check_decorator` how the decorator works in detail.
+        
+In your templates
+-----------------
+::
+
+    {% ifhasperm "flatpage_permission.review_flatpage" request.user flatpage_object %}
+        Yay, you can change *this* flatpage!
+    {% else %}
+        Nope, sorry. You aren't allowed to change *this* flatpage.
+    {% endifhasperm %}
+
+See :ref:`permission_check_in_templates` how the templatetag works in detail.