add a few docs

docs/.gitignore

@@ -0,0 +1,20 @@
+.DS_Store
+.Python
+bin/
+lib/
+dist/
+eggs/
+parts/
+var/
+develop-eggs/
+docs/_build/
+docs/modules/
+include/
+.installed.cfg
+*.egg-info
+*.pt.py
+*.swp
+*.pyc
+*.pyo
+*.log
+*.db

docs/conf.py

@@ -220,6 +220,16 @@ man_pages = [
 intersphinx_mapping = {'http://docs.python.org/': None}
 
 html_theme = 'nature'
+rstctl_exclude = ['fa.jquery.app', 'fa.jquery.pylons']
+
+try:
+    import rstctl
+    extensions.append('rstctl.sphinx')
+except ImportError:
+    pass
+else:
+    del rstctl
+
 from os import path
 pkg_dir = path.abspath(__file__).split('/docs')[0]
 setup = path.join(pkg_dir, 'setup.py')

docs/index.txt

@@ -3,13 +3,65 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+===============================================
 Welcome to pyramid_formalchemy's documentation!
 ===============================================
 
-Contents:
+Installation
+============
+
+With easy_install::
+
+  $ easy_install pyramid_formalchemy
+
+It's also highly recommended to install fa.jquery to get a nicer interface::
+
+  $ easy_install fa.jquery
+
+Usage
+======
+
+Add an empty ``forms.py`` module at the root of your project.
+
+Now you just need to include two line of configuration in the ``__init__.main()`` function of your project.
+Here is the one used for testing:
+
+.. literalinclude:: ../pyramidapp/pyramidapp/__init__.py
+
+This will render the **basic** formalchemy interface.
+
+It's better to enable the jquery stuff like this:
+
+.. literalinclude:: ../../formalchemy_project/__init__.py
+
+
+That's it. Now launch your app, browse ``/admin/`` and enjoy it !
+
+Advanced usage
+===============
+
+In the toward examples we just pass a ``package`` parameter to
+:func:`~pyramid_formalchemy.configure`.  By default the function will try to
+load ``package.models`` ``package.models.DBSession`` and ``package.forms`` but
+you can override this. In this case you don't need to specify a package::
+
+
+    pyramid_formalchemy.configure(config,
+                                  models='formalchemy_project.mymodels',
+                                  session_factory='formalchemy_project.session.Session',
+                                  forms='formalchemy_project',
+                                  use_jquery=True)
+
+You can also change the path ``prefix`` used. pyramid_formalchemy will use
+``/admin/`` by default. See :func:`~pyramid_formalchemy.configure`.
+
+Api
+===
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   modules/index.txt
 
 Indices and tables
 ==================

pyramid_formalchemy/__init__.py

@@ -7,12 +7,12 @@ def include(config):
     config.load_zcml('pyramid_formalchemy:view.zcml')
 
 def include_jquery(config):
-    """include formalchemy's zcml"""
+    """include formalchemy and fa.jquery's zcml """
     config.load_zcml('pyramid.includes:configure.zcml')
     config.load_zcml('pyramid_formalchemy:configure.zcml')
     config.load_zcml('fa.jquery:configure.zcml')
 
-def configure(config, models=None, forms=None, session_factory=None, package=None, use_jquery=True):
+def configure(config, models=None, forms=None, session_factory=None, package=None, prefix='/admin', use_jquery=True):
     """configure formalchemy's admin interface"""
     if models:
         models = config.maybe_dotted(models)
@@ -36,8 +36,8 @@ def configure(config, models=None, forms=None, session_factory=None, package=Non
         })
 
     if use_jquery:
-        config.add_route('fa_admin', '/admin/*traverse',
+        config.add_route('fa_admin', '/%s/*traverse' % prefix,
                          factory='pyramid_formalchemy.resources.AdminView')
     else:
-        config.add_route('fa_admin', '/admin/*traverse',
+        config.add_route('fa_admin', '/%s/*traverse' % prefix,
                          factory='pyramid_formalchemy.resources.AdminView')

pyramidapp/pyramidapp/__init__.py

@@ -2,6 +2,8 @@ from pyramid.config import Configurator
 from sqlalchemy import engine_from_config
 
 from pyramidapp.models import initialize_sql
+
+# import
 import pyramid_formalchemy
 
 def main(global_config, **settings):
@@ -13,8 +15,11 @@ def main(global_config, **settings):
     config.add_static_view('static', 'pyramidapp:static')
     config.add_route('home', '/', view='pyramidapp.views.my_view',
                      view_renderer='templates/mytemplate.pt')
+
+    # pyramid_formalchemy's configuration
     pyramid_formalchemy.include(config)
     pyramid_formalchemy.configure(config, package='pyramidapp')
+
     return config.make_wsgi_app()