adding configuration docs

docs/0.0.1/Makefile

@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Pecan.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Pecan.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Pecan"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Pecan"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/0.0.1/source/app_engine.rst

@@ -0,0 +1,164 @@
+.. _app_engine:
+
+App Engine Support
+=========================
+
+Pecan runs smoothly in Google's App Engine. There is **no** hacking/patching or weird 
+changes that you need to make to work with Pecan. However, since App Engine has certain 
+restrictions you may want to be aware of how to set it up correctly.
+
+.. note::
+    We do not discuss here how to get an App Engine environment here, nor App Engine 
+    specifics that are not related to Pecan. For more info on App Engine go to 
+    `their docs <http://code.google.com/appengine/docs/whatisgoogleappengine.html>`_
+
+
+Dependencies
+---------------
+Pecan has a few dependencies and one of them is already supported by App Engine (WebOb)
+so no need to grab that. Just so you are aware, this is the list of things that you absolutely need 
+to grab:
+
+ *  simplegeneric == 0.7
+ *  Paste == 1.7.5.1
+
+These are optional, depending on the templating engine you want to use. However, depending on your choice,
+you might want to check the engine's dependencies as well. The only engine from this list that doesn't require 
+a dependency is Kajiki.
+
+ *  Genshi == 0.6
+ *  Kajiki == 0.3.1
+ *  Mako == 0.3
+ 
+From this point forward, we will assume you are getting Kajiki, to avoid describing third party dependencies.
+
+
+Creating the project
+============================
+Create a directory called ``pecan_gae`` and ``cd`` into it so we can start adding files. We go step by 
+step into what needs to go there to get everything running properly.
+
+app.yaml
+------------
+
+To start off, you will need your ``app.yaml`` file set properly to map to Pecan. This is how that file should look
+like::
+
+    application: foo-bar
+    version: 1
+    runtime: python
+    api_version: 1
+
+    handlers:
+
+    - url: /.*
+      script: main.py
+
+Remember the application name will have to match your registered app name in App Engine. The file above maps 
+everything to a ``main.py`` file.
+
+This file will be the *root* of our project and will handle everything. 
+
+main.py 
+------------
+You can name this anything you want, but for consistency we are going with main.py. This file will handle 
+all the incoming requests including static files for our Pecan application. This is how it should look::
+
+    from google.appengine.ext.webapp import util
+    import sys
+    if './lib' not in sys.path:
+        sys.path.append('./lib')
+
+    from pecan import Pecan, expose
+
+
+    class RootController(object):
+
+        @expose('kajiki:index.html')
+        def index(self):
+            return dict(name="Joe Wu Zap")
+
+
+    def main():
+        application = Pecan(RootController(), template_path='templates')
+        util.run_wsgi_app(application)
+
+
+    if __name__ == '__main__':
+        main()
+
+We are doing a few things here... first we are importing the ``util`` module from App Engine that will 
+run our Pecan app, then we are importing ``sys`` because we need to add ``lib`` to our path.
+
+The ``lib`` directory is where all our dependencies (including Pecan) will live, so we need to make sure
+App Engine will see that as well as all our libraries within ``lib`` (it would not be enough to add a ``__init__.py``
+file there.
+
+templates
+-----------
+The templates directory is where we will have all of our html templates for Pecan. If you don't have it already, go ahead 
+and create it and add this html file to it and name it index.html::
+
+    <html>
+
+    <head>
+      <title>Hello, ${name}!</title>  
+    </head>
+
+    <body>
+      <h1>Hello, ${name}!</h1>
+    </body>
+
+    </html>
+
+lib
+-----
+The ``lib`` directory should contain the source for all the dependencies we need. For our example, it should
+contain 3 libraries:
+
+ * kajiki
+ * paste 
+ * pecan 
+
+That is all you need to get this project started!
+
+.. note::
+    When grabing the source of the dependencies we mention, make sure you are actually grabing the module itself 
+    and not adding the top directory source (where setup.py lives)
+
+Layout
+---------
+This is how your layout (only showing directories) should look like::
+
+    pecan_gae
+    |____app.yaml
+    |____lib
+    | |____kajiki
+    | | |____tests
+    | |   |____data
+    | |____paste
+    | | |____auth
+    | | |____cowbell
+    | | |____debug
+    | | |____evalexception
+    | | | |____media
+    | | |____exceptions
+    | | |____util
+    | |____pecan
+    |____templates
+
+
+Trying it out
+=========================
+Now everything should be ready to start serving, so go ahead and run the development server::
+
+    $ ./dev_appserver.py pecan_gae 
+    INFO     2010-10-10 12:44:29,476 dev_appserver_main.py:431] Running application pecan-gae on port 8080: http://localhost:8080
+    
+
+If you go to your browser and hit ``localhost:8080`` you should see something like this::
+
+        Hello, Joe Wu Zap!
+
+This is the most basic example for App Engine, you can start adding more controllers to handle a bigger 
+application and connect everything together. 

docs/0.0.1/source/conf.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# Pecan documentation build configuration file, created by
+# sphinx-quickstart on Sat Oct  9 14:41:27 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Pecan'
+copyright = u'2010, Jonathan LaCour'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Pecandoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'Pecan.tex', u'Pecan Documentation',
+   u'Jonathan LaCour', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'pecan', u'Pecan Documentation',
+     [u'Jonathan LaCour'], 1)
+]

docs/0.0.1/source/configuration.rst

@@ -0,0 +1,77 @@
+.. _configuration:
+
+Configuration
+=============
+Pecan is very easy to configured. As long as you follow certain conventions;
+using, setting and dealing with configuration should be very intuitive.
+
+Python files is what the framework uses to get the values from configuration
+files. These files need to specify the values in a key/value way (Python
+dictionaries).
+
+Even if you want custom configuration values, you need to get them in the
+configuration file as dictionaries.
+
+No Configuration
+----------------
+What happens when no configuration is passed? Or if you are missing some values?
+Pecan fills in anything that you might have left behind. This includes either
+**app** or **server** completely and even if you left out specifics about them,
+like the port number the server should be running on. 
+
+Defaults
+--------
+Below is the complete default values the framework uses::
+
+
+    server = {
+        'port' : '8080',
+        'host' : '0.0.0.0'
+    }
+
+    app = {
+        'root' : None,
+        'static_root' : 'public', 
+        'template_path' : '',
+        'debug' : False
+    }
+
+
+
+.. _application_configuration:
+
+Application Configuration
+-------------------------
+This is the part of the configuration that is specific to your application.
+Things like debug mode, Root Controller and possible Hooks, should be specified
+here. This is what is used when the framework is wrapping your application into
+a valid WSGI app.
+
+A typical application configuration would look like this::
+
+    app = {
+        'root' : RootController(),
+        'static_root' : 'public', 
+        'template_path' : 'project/templates',
+        'debug' : True 
+    }
+
+Let's look at each value and what it means:
+
+**app** is a reserved variable name for the configuration, so make sure you are
+not overriding, otherwise you will get default values.
+
+**root** Needs the Root Controller of your application, this where your main
+class that points to all the spots in your application should be. Rememeber
+that you are passing the actual object so you would need to import it at the
+top of the file. In the example configuration, this would be something like::
+
+    from myproject.controllers.root import RootController
+
+**static_root** Points to the directory where your static files live in.
+
+**template_path** The path where your templates are. 
+
+**debug** Enables ``WebError`` to have full tracebacks in the browser (this is
+OFF by default).
+

docs/0.0.1/source/index.rst

@@ -0,0 +1,122 @@
+.. Pecan documentation master file, created by
+   sphinx-quickstart on Sat Oct  9 14:41:27 2010.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Pecan's documentation
+=========================
+
+A WSGI object-dispatching web framework, in the spirit of TurboGears, only 
+much much smaller, with many fewer dependencies.
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   installation.rst
+   routing.rst 
+   configuration.rst 
+   templates.rst 
+   hooks.rst 
+   jsonify.rst 
+   secure_controller.rst 
+   validation_n_errors.rst
+
+
+Introduction
+============
+Pecan packs a few good features but it is also extremely lean, it requires just
+a few dependencies but for the most part it feels like a full fledged web
+framework!
+
+ * Object-Dispatch for easy routing
+ * Pre and Post Hooks 
+ * REST controllers 
+ * Validation and Error handling
+ * Secure controllers
+ * Template language support
+ * AppEngine out of the box (no patching!)
+
+
+
+Pecan Hello World
+------------------
+In this example we use ``httpserver`` from ``paste`` but feel free to use any 
+WSGI server you want::
+
+    from paste import httpserver
+    from pecan import make_app, expose
+
+
+    class RootController(object):
+
+        @expose()
+        def index(self):
+            return 'Hello, World!'
+
+    app = make_app(RootController(), debug=True)
+    httpserver.serve(app, host='0.0.0.0', port=8080)
+
+
+Tutorials
+=========
+We provide a couple of easy ways to get started including a short tutorial on
+App Engine.
+
+.. toctree::
+   :maxdepth: 2
+
+   quick_start.rst 
+   app_engine.rst
+
+
+API
+===
+The following section lists the main sections of Pecan, where you can find more
+specific details about methods and modules available.
+
+.. toctree::
+   :maxdepth: 2
+
+   decorators.rst 
+   hooks.rst 
+   jsonify.rst 
+   pecan.rst 
+   rest.rst 
+   routing.rst 
+   secure.rst
+   templating.rst
+
+License
+-------
+The Pecan framework and the documentation is BSD Licensed::
+
+    Copyright (c) <2010>, Pecan Framework
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+        * Neither the name of the <organization> nor the
+          names of its contributors may be used to endorse or promote products
+          derived from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+

docs/0.0.1/source/installation.rst

@@ -0,0 +1,45 @@
+.. _installation:
+
+Installation
+============
+We recommend installing Pecan with ``pip`` but you can also try with
+``easy_install`` and ``virtualenv``. Creating a spot in your environment where
+Pecan can be isolated from other packages is best practice.
+
+To get started with an environment for Pecan, create a virtual environment for
+it without any site-packages that might pollute::
+
+    virtualenv --no-site-packages pecan-env
+    cd pecan-env 
+    source bin/activate
+
+The above commands created a virtual environment and *activated* it. Those
+actions will encapsulate anything that we do with the framework, making it
+easier to debug problems if needed.
+
+But we do not have Pecan yet, so let's grab it from PYPI::
+
+    pip install pecan 
+
+After a lot of output, you should have Pecan successfully installed and ready
+to use.
+
+
+Development (Unstable) Version
+------------------------------
+If you want to run the development version of Pecan you will
+need GIT installed and clone the repo from github::
+
+    git clone https://github.com/cleverdevil/pecan.git
+
+If you are still in the *pecan-dev* virtual environment that we created before,
+you should call ``setup.py`` to install::
+
+    python setup.py develop
+
+
+Testing
+=======
+For testing purposes, we use `py.test <http://pytest.org/>`_ and
+WebTest, so make sure you have those installed in your environment before
+running the tests.  

docs/0.0.1/source/quick_start.rst

@@ -0,0 +1,201 @@
+.. _quick_start:
+
+Quick Start
+===========
+Here we will cover the basics for a small project in Pecan. More advanced
+examples and methods are not covered here.
+
+.. note::
+    We will not cover how to get Pecan installed here. If you need installation
+    details please go to :ref:`installation`
+
+
+We include a basic template to have a good layout for a Pecan project. This is
+accomplished by ``PasteScript`` so we need to invoke a command to create our
+example project::
+
+    $ paster create -t pecan-base
+
+The above commnad will prompt you for a project name. I chose *test_project*,
+this is how it looks like when we run the whole command:: 
+
+    $ paster create -t pecan-base
+    Selected and implied templates:
+      pecan#pecan-base  Template for creating a basic Framework package
+
+    Enter project name: test_project
+    Variables:
+      egg:      test_project
+      package:  test_project
+      project:  test_project
+    Creating template pecan-base
+    Creating directory ./test_project
+      Recursing into +egg+
+        Creating ./test_project/test_project/
+        Copying __init__.py to ./test_project/test_project/__init__.py
+        Recursing into controllers
+          Creating ./test_project/test_project/controllers/
+          Copying __init__.py to ./test_project/test_project/controllers/__init__.py
+          Copying root.py to ./test_project/test_project/controllers/root.py
+        Recursing into templates
+          Creating ./test_project/test_project/templates/
+          Copying index.html to ./test_project/test_project/templates/index.html
+          Copying layout.html to ./test_project/test_project/templates/layout.html
+          Copying success.html to ./test_project/test_project/templates/success.html
+      Recursing into public
+        Creating ./test_project/public/
+        Recursing into css
+          Creating ./test_project/public/css/
+          Copying style.css to ./test_project/public/css/style.css
+        Recursing into javascript
+          Creating ./test_project/public/javascript/
+          Copying shared.js to ./test_project/public/javascript/shared.js
+      Copying start.py_tmpl to ./test_project/start.py
+
+
+This is how the structure of your new project should look like::
+
+    .
+    ├── config.py
+    ├── public
+    │   ├── css
+    │   │   └── style.css
+    │   └── javascript
+    │       └── shared.js
+    ├── start.py
+    └── test_project
+        ├── __init__.py
+        ├── controllers
+        │   ├── __init__.py
+        │   └── root.py
+        └── templates
+            ├── index.html
+            ├── layout.html
+            └── success.html
+
+    6 directories, 10 files
+
+
+A few things have been set for you, let's review them one by one:
+
+*  **public**: All your public static files like CSS and Javascript are placed
+  here. If you have some images (this example app doesn't) it would make sense
+  to get them here as well.
+
+
+Inside the project name you chose you have a couple of directories, and for the
+most part, it will contain your models, controllers and templates:
+
+*  **controllers**: The container directory for your controller files. 
+*  **templates**: All your templates would go in here. 
+
+Note how there is no **model** directory. Since we haven't defined any
+database for the app the template doesn't supply you one. In case you need it
+later you could create a ``models.py`` file or a ``model`` directory.
+
+
+.. _running_application:
+
+Running the application
+-----------------------
+There are 2 files that are important to start your application. In this case
+``start.py`` and ``config.py`` are in charge of getting everything up and running.
+
+If you just run ``start.py`` with Python, passing ``config`` as an argument for
+configuration it will bring up the development server and serve the app::
+
+    python start.py config
+    Serving on http://0.0.0.0:8080
+    serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
+    
+To get up and running in no time the template helps a lot! 
+
+.. note::
+    If you fail to pass an argument you will get a small error message asking
+    for a configuration file. Remember you need to pass the name of the
+    configuration file without the ".py" extension. 
+
+
+Simple Configuration
+--------------------
+We mentioned that you get a Python file with some configurations. The only
+Python syntax that you will see is the first line that imports the
+RootController that is in turn placed as the application root. Everything else,
+including possible custom configurations are set as Python dictionaries.
+
+This is how your default configuration file should look like::
+
+    from test_project.controllers.root import RootController
+
+
+    # Server Specific Configurations
+    server = {
+        'port' : '8080',
+        'host' : '0.0.0.0'
+    }
+
+    # Pecan Application Configurations
+    app = {
+        'root' : RootController(),
+        'static_root' : 'public', 
+        'template_path' : 'test_project/templates',
+        'debug' : True 
+    }
+
+    # Custom Configurations must be in Python dictionary format::
+    #
+    # foo = {'bar':'baz'}
+    # 
+    # All configurations are accessible at::
+    # pecan.conf
+
+
+**Nothing** in the configuration file above is actually required for Pecan to
+be able to run. If you fail to provide some values Pecan will fill in the
+missing things it needs to run.
+
+You also get the ability to set your own configurations as dictionaries and you
+get a commented out example on how to do that.
+
+We are not going to explain much more about configuration here, if you need
+more specific details, go to the :ref:Configuration section.
+
+    
+Root Controller
+---------------
+The Root Controller is the main point of contact between your application and
+the framework.
+
+This is how it looks from the project template::
+
+    from pecan import expose, request
+    from formencode import Schema, validators as v
+
+
+    class SampleForm(Schema):
+        name = v.String(not_empty=True)
+        age = v.Int(not_empty=True)
+
+
+    class RootController(object):
+        @expose('index.html')
+        def index(self, name='', age=''):
+            return dict(errors=request.validation_error, name=name, age=age)
+        
+        @expose('success.html', schema=SampleForm(), error_handler='index')
+        def handle_form(self, name, age):
+            return dict(name=name, age=age)
+
+
+Here you can specify other classes if you need to do so later on your project,
+but for now we have an *index* method and a *handle_form* one.
+
+**index**: Is *exposed* as the root of the application, so anything that hits
+'/' will touch this method.
+Since we are doing some validation and want to pass any errors we might get to
+the template, we set ``errors`` to receive anything that
+``request.validation_error`` returns.
+
+
+**handle_form**: It receives 2 parameters (*name* and *age*) that are validated
+through the *SampleForm* schema class.