.. -*-rst-*-

Introduction
============

RapidGiza is a set of Paster templates that provide out of the box:

  * An application based on the Pyramid_ web application framework

  * Default SQLAlchemy_ engine/session-factory setup

  * All ``.html`` files matched as Jinja2_ templates

  * Werkzeug_ setup for running the app in development mode

Setting up a New Project
========================

Install RapidGiza into a Python environment (ie virtualenv_) with a working
Paster.  Once this has been done, you can create a new RapidGiza project
by simply running (where *Something* is the name of your new egg)::

  paster create -t rapidgiza Something

Once the template egg has been created you should set it up in develop
mode to start working on your project.
::

  cd Something
  python setup.py develop

Now you can run the ready-to-run egg by issuing::

  python -m something.main runserver

At which point you should now be able to go to your browser
using http://127.0.0.1:8080 and see the new *Welcome to Something*
page.

Using the New Project
=====================

Base Framework
--------------

RapidGiza is based on the amazing Pyramid_ web application
framework.  As such, the Pyramid_ api will always be
the go-to api for building up the web application.  Please
see the `Pyramid docs`_ for future details.

Templating
----------

Any file ending with the ``.html`` extension located inside
the ``Something/something/templates`` will be rendered using
the Jinja2_ templating system.  This template language is
based on the Django templating language.

Data Access
-----------

All data access is handled by the SQLAlchemy_ ORM_ framework which wraps
relational databases.  Out of the box, any new project created by RapidGiza
will have a SQLAlchemy_ database session factory setup.

Developing/Debugging
--------------------

The Werkzeug_ library is used to provide two things:

  1. A very useful debugging middleware

  2. A command runner (what you get when ``python -m something.main`` is run)

Before any data access code can be run, simply run::

  python -m something.main syncdb

The ``runserver`` command can be run with various debugging and verbosity
options, please see the ``--help`` output for details::

  python -m something.main --help
  runserver:
    Run the development server.
    
    :param debug: run in debug mode
    :param verbosity: increase level of logging for more verbose logging

    -h, --hostname                string    0.0.0.0
    -p, --port                    integer   8080
    -d, --debug
    -v, --verbosity               integer   0

Credits
=======

RapidGiza is written and maintained by Rocky Burt
(rocky AT serverzen DOT com).

.. _Jinja2: http://jinja.pocoo.org/
.. _Pyramid: http://docs.pylonshq.com/
.. _`Pyramid Docs`: http://docs.pylonshq.com/pyramid/dev/
.. _Werkzeug: http://werkzeug.pocoo.org/
.. _SQLAlchemy: http://www.sqlalchemy.org/
.. _orm: http://en.wikipedia.org/wiki/Object-relational_mapping
.. _virtualenv: http://pypi.python.org/pypi/virtualenv
