more docs and a bit of refactoring since the index page becoming big

docs/index.txt

@@ -142,6 +142,16 @@ and per Model::
                                   request_method='GET',
                                   permission='view')
 
+Events
+=======
+
+pyramid_formalchemy got some hooks to help you to customize things. See :mod:`pyramid_formalchemy.events`.
+
+Actions
+=======
+
+pyramid_formalchemy allow you to customize links and actions of your views. See :mod:`pyramid_formalchemy.actions`.
+
 Setting permissions
 ===================
 
@@ -162,22 +172,11 @@ You can also add an ``__acl__`` attribute to your model class:
 .. literalinclude:: ../pyramidapp/pyramidapp/models.py
    :pyobject: Bar
 
-Event subscription
-==================
-
-``pyramid_formalchemy`` provides four events: ``IBeforeValidateEvent``, 
-``IAfterSyncEvent``, ``IBeforeDeleteEvent`` and ``IBeforeRenderEvent``. 
-There are also two more specific render evnts: ``IBeforeShowRenderEvent``
-and ``IBeforeEditRenderEvent``. You can use ``pyramid_formalchemy.events.subscriber`` 
-decorator to subscribe:
-
-.. literalinclude:: ../pyramidapp/pyramidapp/events.py
-
 Api
 ===
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    modules/index.txt
 

pyramid_formalchemy/actions.py

@@ -14,19 +14,27 @@ By default there is only one category ``buttons`` which are the forms buttons
 but you can add some categories like this::
 
     >>> from pyramid_formalchemy.views import ModelView
-    >>> class MyView(ModelView)
+    >>> from pyramid_formalchemy import actions
+
+    >>> class MyView(ModelView):
     ...     # keep default action categorie and add the custom_actions categorie
     ...     actions_categories = ('buttons', 'custom_actions')
     ...     # update the default actions for all models
-    ...     defaults_actions = actions_categories.defaults_actions.copy()
-    ...     defaults_actions.update(edit_custom_actions=myactions)
+    ...     defaults_actions = actions.defaults_actions.copy()
+    ...     defaults_actions.update(edit_custom_actions=Actions())
 
 Where ``myactions`` is an :class:`~pyramid_formalchemy.actions.Actions` instance
 
 You can also customize the actions per Model::
 
+
+    >>> from sqlalchemy import Column, Integer
+    >>> from sqlalchemy.ext.declarative import declarative_base
+    >>> Base = declarative_base()
     >>> class MyArticle(Base):
+    ...     __tablename__ = 'myarticles'
     ...     edit_buttons = Actions()
+    ...     id = Column(Integer, primary_key=True)
 
 The available actions are:
 
@@ -40,7 +48,7 @@ But you can add your own::
 
     >>> from pyramid_formalchemy.views import ModelView
     >>> from pyramid_formalchemy import actions
-    >>> class MyView(ModelView)
+    >>> class MyView(ModelView):
     ...     actions.action()
     ...     def extra(self):
     ...         # do stuff
@@ -234,20 +242,22 @@ class Actions(list):
         <a href="http://localhost" id="link1">A link</a>
         
     """
-
-    def __init__(self, *args):
+    tag = u''
+    def __init__(self, *args, **kwargs):
         res = DottedNameResolver('pyramid_formalchemy.actions')
         list.__init__(self, [res.maybe_resolve(a) for a in args])
 
     def render(self, request, **kwargs):
         return u'\n'.join([a.render(request, **kwargs) for a in self])
 
+
+
 class Languages(Actions):
     """Languages actions::
 
         >>> langs = Languages('fr', 'en')
         >>> langs
-        [<ListItem fr>, <ListItem en>]
+        [<ListItem lang_fr>, <ListItem lang_en>]
 
     It take care about the active language::
 

pyramid_formalchemy/events.py

@@ -1,4 +1,18 @@
 import zope.component
+__doc__ = """
+Event subscription
+==================
+
+``pyramid_formalchemy`` provides four events: ``IBeforeValidateEvent``,
+``IAfterSyncEvent``, ``IBeforeDeleteEvent`` and ``IBeforeRenderEvent``.
+There are also two more specific render evnts: ``IBeforeShowRenderEvent``
+and ``IBeforeEditRenderEvent``. You can use ``pyramid_formalchemy.events.subscriber``
+decorator to subscribe:
+
+.. literalinclude:: ../../pyramidapp/pyramidapp/events.py
+
+"""
+
 
 class IBeforeValidateEvent(zope.component.interfaces.IObjectEvent):
     """A model will be validated"""

pyramid_formalchemy/i18n.py

@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+__doc__ = """Model translation.
+"""
+
+
 from pyramid.i18n import TranslationStringFactory
 from pyramid.i18n import TranslationString
 from pyramid.i18n import get_localizer

pyramid_formalchemy/resources.py

@@ -7,6 +7,15 @@ import logging
 log = logging.getLogger(__name__)
 
 class Base(object):
+    """Base class used for all traversed class.
+    Allow to access to some useful attributes via request::
+
+    - model_class
+    - model_name
+    - model_instance
+    - model_id
+    - fa_url
+    """
 
     def __init__(self, request, name):
         self.__name__ = name
@@ -73,6 +82,7 @@ class Base(object):
 
 
 class Models(Base):
+    """Root of the CRUD interface"""
 
     def __init__(self, request):
         Base.__init__(self, request, None)
@@ -99,6 +109,7 @@ class Models(Base):
         return model
 
 class ModelListing(Base):
+    """Context used for model classes"""
 
     def __init__(self, request, name=None):
         Base.__init__(self, request, name)
@@ -132,6 +143,7 @@ class ModelListing(Base):
         return model
 
 class Model(Base):
+    """Context used for model instances"""
 
     def fa_url(self, *args, **kwargs):
         return self._fa_url(*args[2:], **kwargs)