diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..61eb318
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+_build/*
\ No newline at end of file
diff --git a/_build/doctrees/environment.pickle b/_build/doctrees/environment.pickle
index b0f9e4c..677977a 100644
Binary files a/_build/doctrees/environment.pickle and b/_build/doctrees/environment.pickle differ
diff --git a/_build/doctrees/index.doctree b/_build/doctrees/index.doctree
index 4fc1076..145531e 100644
Binary files a/_build/doctrees/index.doctree and b/_build/doctrees/index.doctree differ
diff --git a/_build/html/_sources/index.txt b/_build/html/_sources/index.txt
index 55e412a..fb9babe 100644
--- a/_build/html/_sources/index.txt
+++ b/_build/html/_sources/index.txt
@@ -3,18 +3,9 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to osxpython's documentation!
+Welcome to OSXPython.org
 =====================================
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Welcome to OSXPython.org. This site exists to provide novice and expert Python developers using OS X a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
 
+.. include:: contents.rst.inc
\ No newline at end of file
diff --git a/_build/html/index.html b/_build/html/index.html
index 02f1b10..d9d779c 100644
--- a/_build/html/index.html
+++ b/_build/html/index.html
@@ -6,7 +6,7 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Welcome to osxpython’s documentation! &mdash; osxpython v0.0.1 documentation</title>
+    <title>Welcome to OSXPython.org &mdash; osxpython v0.0.1 documentation</title>
     <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript">
@@ -43,21 +43,36 @@
         <div class="bodywrapper">
           <div class="body">
             
-  <div class="section" id="welcome-to-osxpython-s-documentation">
-<h1>Welcome to osxpython&#8217;s documentation!<a class="headerlink" href="#welcome-to-osxpython-s-documentation" title="Permalink to this headline">¶</a></h1>
-<p>Contents:</p>
+  <div class="section" id="welcome-to-osxpython-org">
+<h1>Welcome to OSXPython.org<a class="headerlink" href="#welcome-to-osxpython-org" title="Permalink to this headline">¶</a></h1>
+<p>Welcome to OSXPython.org. This site exists to provide novice and expert Python developers using OS X a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.</p>
+<div class="section" id="user-s-guide">
+<h2>User&#8217;s Guide<a class="headerlink" href="#user-s-guide" title="Permalink to this headline">¶</a></h2>
+<p>This part of the documentation, which is mostly prose, begins with some
+background information about Flask, then focuses on step-by-step
+instructions for web development with Flask.</p>
 <div class="toctree-wrapper compound">
 <ul class="simple">
 </ul>
 </div>
 </div>
-<div class="section" id="indices-and-tables">
-<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="api-reference">
+<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>
+<p>If you are looking for information on a specific function, class or
+method, this part of the documentation is for you.</p>
+<div class="toctree-wrapper compound">
 <ul class="simple">
-<li><a class="reference internal" href="genindex.html"><em>Index</em></a></li>
-<li><a class="reference internal" href="py-modindex.html"><em>Module Index</em></a></li>
-<li><a class="reference internal" href="search.html"><em>Search Page</em></a></li>
 </ul>
+</div>
+</div>
+<div class="section" id="additional-notes">
+<h2>Additional Notes<a class="headerlink" href="#additional-notes" title="Permalink to this headline">¶</a></h2>
+<p>Design notes, legal information and changelog are here for the interested.</p>
+<div class="toctree-wrapper compound">
+<ul class="simple">
+</ul>
+</div>
+</div>
 </div>
 
 
@@ -68,10 +83,18 @@
         <div class="sphinxsidebarwrapper">
   <h3><a href="#">Table Of Contents</a></h3>
   <ul>
-<li><a class="reference internal" href="#">Welcome to osxpython&#8217;s documentation!</a><ul>
+<li><a class="reference internal" href="#">Welcome to OSXPython.org</a><ul>
+<li><a class="reference internal" href="#user-s-guide">User&#8217;s Guide</a><ul>
+</ul>
+</li>
+<li><a class="reference internal" href="#api-reference">API Reference</a><ul>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-notes">Additional Notes</a><ul>
+</ul>
+</li>
 </ul>
 </li>
-<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
 </ul>
 <h3>Related Topics</h3>
 <ul>
diff --git a/_build/html/searchindex.js b/_build/html/searchindex.js
index 70f636e..aef0bd1 100644
--- a/_build/html/searchindex.js
+++ b/_build/html/searchindex.js
@@ -1 +1 @@
-Search.setIndex({objects:{},terms:{index:0,search:0,welcom:0,osxpython:0,modul:0,indic:0,content:0,tabl:0,document:0,page:0},objtypes:{},titles:["Welcome to osxpython&#8217;s documentation!"],objnames:{},filenames:["index"]})
\ No newline at end of file
+Search.setIndex({objects:{},terms:{code:[1,2],execut:[1,2],thi:[0,1,2],becaus:[1,2],session:[1,2],still:[1,2],process_respons:[1,2],paramet:[1,2],redirect:[1,2],web:0,onli:[1,2],depend:[1,2],just:[1,2],flask:[0,1,2],configur:0,except:[1,2],should:[1,2],common:[1,2],sens:[1,2],main:[1,2],might:[1,2],unittest:[1,2],real:[1,2],applic:[1,2],them:[1,2],"return":[1,2],around:[1,2],get:[1,2],python:[0,1,2],handi:[1,2],initi:[1,2],focus:0,util:[1,2],framework:2,background:0,veri:[1,2],bit:[1,2],now:2,requir:[1,2],like:[1,2],install_homebrew:2,specif:[0,1,2],changelog:0,drop:[1,2],probabl:[1,2],"try":[1,2],easili:[1,2],stuff:[1,2],either:[1,2],plain:[1,2],attribut:[1,2],where:[1,2],page:[1,2],mean:[1,2],imagin:[1,2],some:[0,1,2],back:[1,2],see:[1,2],design:0,result:[1,2],arg:[1,2],further:[1,2],best:0,index:[1,2],what:[1,2],expert:0,databas:[1,2],legal:0,your:[1,2],content:[],nonetyp:[1,2],"import":[1,2],experi:[1,2],method:[0,1,2],refer:0,altern:[1,2],after:[1,2],run:[1,2],osxpython:0,situat:[1,2],here:0,pleasant:[1,2],step:0,upfront:[1,2],put:[1,2],org:0,"byte":[1,2],come:[1,2],addit:0,about:0,last:[1,2],wai:[1,2],befor:[1,2],attributeerror:[1,2],howev:[1,2],current:[1,2],ctx:[1,2],reason:[1,2],preprocess_request:[1,2],keep:[1,2],etc:[1,2],response_class:[1,2],redirect_url:[1,2],shelltool:[1,2],improv:[1,2],com:[1,2],oper:[1,2],onward:[1,2],love:[1,2],point:[1,2],app:[1,2],pop:[1,2],yourself:[1,2],instruct:0,api:0,done:[1,2],shutdown:[1,2],fake:[1,2],instal:[0,2],guid:0,referr:[1,2],avail:[1,2],from:[1,2],creat:[1,2],would:[1,2],interact:[1,2],two:[1,2],next:[1,2],everybodi:[1,2],start:[1,2],trigger:[1,2],handbook:0,statement:[1,2],basic:[1,2],call:[1,2],immedi:[1,2],until:[1,2],store:[1,2],more:[1,2],"function":[0,1,2],shell:[1,2],consol:[1,2],interest:0,fire:[1,2],rubi:2,search:[],idea:[1,2],part:0,push:[1,2],mostli:0,don:[1,2],line:[1,2],"case":[1,2],url_for:[1,2],look:0,provid:0,local:[1,2],setup:[1,2],work:[1,2],exampl:[1,2],trick:[1,2],defin:[1,2],can:[1,2],site:0,modul:[1,2],star:[1,2],could:[1,2],def:[1,2],browser:[1,2],novic:0,sai:[1,2],traceback:[1,2],file:[1,2],helper:[1,2],sudo:2,mind:[1,2],ani:[1,2],indic:[],raw:2,itself:[1,2],exist:0,unavail:[1,2],have:[1,2],tabl:[1,2],prose:0,curl:2,unfortun:[1,2],gist:2,alwai:[1,2],develop:0,welcom:0,want:[1,2],thing:[1,2],titl:[],make:[1,2],access:[1,2],note:0,also:[1,2],need:[1,2],other:[1,2],which:[0,1,2],test:[1,2],ignor:[1,2],you:[0,1,2],document:0,basi:0,begin:0,http:[1,2],context:[1,2],normal:[1,2],dive:[1,2],object:[1,2],test_request_context:[1,2],most:[1,2],plai:[1,2],lot:[1,2],user:[0,1,2],respons:[1,2],"class":0,recent:[1,2],github:2,usag:[0,1,2],practic:0,url:[1,2],bind:[1,2],stdin:[1,2],request:[1,2],doe:[1,2],issu:[1,2],inform:0,fss:2,command:[1,2],allow:[1,2],time:[1,2],brew:2,daili:0},objtypes:{},titles:["Welcome to OSXPython.org","Working with the Shell","Working with the Shell"],objnames:{},filenames:["index","shell","installation"]})
\ No newline at end of file
diff --git a/contents.rst.inc b/contents.rst.inc
new file mode 100644
index 0000000..de66248
--- /dev/null
+++ b/contents.rst.inc
@@ -0,0 +1,53 @@
+
+User's Guide
+------------
+
+This part of the documentation, which is mostly prose, begins with some
+background information about Flask, then focuses on step-by-step
+instructions for web development with Flask.
+
+.. toctree::
+   :maxdepth: 2
+
+   foreword
+   installation
+   quickstart
+   tutorial/index
+   templating
+   testing
+   errorhandling
+   config
+   signals
+   shell
+   patterns/index
+   deploying/index
+   becomingbig
+
+API Reference
+-------------
+
+If you are looking for information on a specific function, class or
+method, this part of the documentation is for you.
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+
+Additional Notes
+----------------
+
+Design notes, legal information and changelog are here for the interested.
+
+.. toctree::
+   :maxdepth: 2
+
+   design
+   htmlfaq
+   security
+   unicode
+   extensiondev
+   styleguide
+   upgrading
+   changelog
+   license
\ No newline at end of file
diff --git a/index.rst b/index.rst
index 55e412a..fb9babe 100644
--- a/index.rst
+++ b/index.rst
@@ -3,18 +3,9 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to osxpython's documentation!
+Welcome to OSXPython.org
 =====================================
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Welcome to OSXPython.org. This site exists to provide novice and expert Python developers using OS X a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
 
+.. include:: contents.rst.inc
\ No newline at end of file
diff --git a/installation.rst b/installation.rst
new file mode 100644
index 0000000..ff930ae
--- /dev/null
+++ b/installation.rst
@@ -0,0 +1,117 @@
+Working with the Shell
+======================
+
+.. versionadded:: 0.3
+
+One of the reasons everybody loves Python is the interactive shell.  It
+basically allows you to execute Python commands in real time and
+immediately get results back.  Flask itself does not come with an
+interactive shell, because it does not require any specific setup upfront,
+just import your application and start playing around. ::
+
+    $ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)"
+
+And we can now install python: ::
+
+    $ sudo brew install python --framework
+
+
+There are however some handy helpers to make playing around in the shell a
+more pleasant experience.  The main issue with interactive console
+sessions is that you're not triggering a request like a browser does which
+means that :data:`~flask.g`, :data:`~flask.request` and others are not
+available.  But the code you want to test might depend on them, so what
+can you do?
+
+This is where some helper functions come in handy.  Keep in mind however
+that these functions are not only there for interactive shell usage, but
+also for unittesting and other situations that require a faked request
+context.
+
+Diving into Context Locals
+--------------------------
+
+Say you have a utility function that returns the URL the user should be
+redirected to.  Imagine it would always redirect to the URL's ``next``
+parameter or the HTTP referrer or the index page::
+
+    from flask import request, url_for
+
+    def redirect_url():
+        return request.args.get('next') or \
+               request.referrer or \
+               url_for('index')
+
+As you can see, it accesses the request object.  If you try to run this
+from a plain Python shell, this is the exception you will see:
+
+>>> redirect_url()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+AttributeError: 'NoneType' object has no attribute 'request'
+
+That makes a lot of sense because we currently do not have a request we
+could access.  So we have to make a request and bind it to the current
+context.  The :attr:`~flask.Flask.test_request_context` method can create
+us a request context:
+
+>>> ctx = app.test_request_context('/?next=http://example.com/')
+
+This context can be used in two ways.  Either with the `with` statement
+(which unfortunately is not very handy for shell sessions).  The
+alternative way is to call the `push` and `pop` methods:
+
+>>> ctx.push()
+
+From that point onwards you can work with the request object:
+
+>>> redirect_url()
+u'http://example.com/'
+
+Until you call `pop`:
+
+>>> ctx.pop()
+>>> redirect_url()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+AttributeError: 'NoneType' object has no attribute 'request'
+
+
+Firing Before/After Request
+---------------------------
+
+By just creating a request context, you still don't have run the code that
+is normally run before a request.  This probably results in your database
+being unavailable, the current user not being stored on the
+:data:`~flask.g` object etc.
+
+This however can easily be done yourself.  Just call
+:meth:`~flask.Flask.preprocess_request`:
+
+>>> ctx = app.test_request_context()
+>>> ctx.push()
+>>> app.preprocess_request()
+
+Keep in mind that the :meth:`~flask.Flask.preprocess_request` function
+might return a response object, in that case just ignore it.
+
+To shutdown a request, you need to trick a bit before the after request
+functions (triggered by :meth:`~flask.Flask.process_response`) operate on
+a response object:
+
+>>> app.process_response(app.response_class())
+<Response 0 bytes [200 OK]>
+>>> ctx.pop()
+
+
+Further Improving the Shell Experience
+--------------------------------------
+
+If you like the idea of experimenting in a shell, create yourself a module
+with stuff you want to star import into your interactive session.  There
+you could also define some more helper methods for common things such as
+initializing the database, dropping tables etc.
+
+Just put them into a module (like `shelltools` and import from there):
+
+>>> from shelltools import *
diff --git a/shell.rst b/shell.rst
new file mode 100644
index 0000000..470bcec
--- /dev/null
+++ b/shell.rst
@@ -0,0 +1,110 @@
+Working with the Shell
+======================
+
+.. versionadded:: 0.3
+
+One of the reasons everybody loves Python is the interactive shell.  It
+basically allows you to execute Python commands in real time and
+immediately get results back.  Flask itself does not come with an
+interactive shell, because it does not require any specific setup upfront,
+just import your application and start playing around.
+
+There are however some handy helpers to make playing around in the shell a
+more pleasant experience.  The main issue with interactive console
+sessions is that you're not triggering a request like a browser does which
+means that :data:`~flask.g`, :data:`~flask.request` and others are not
+available.  But the code you want to test might depend on them, so what
+can you do?
+
+This is where some helper functions come in handy.  Keep in mind however
+that these functions are not only there for interactive shell usage, but
+also for unittesting and other situations that require a faked request
+context.
+
+Diving into Context Locals
+--------------------------
+
+Say you have a utility function that returns the URL the user should be
+redirected to.  Imagine it would always redirect to the URL's ``next``
+parameter or the HTTP referrer or the index page::
+
+    from flask import request, url_for
+
+    def redirect_url():
+        return request.args.get('next') or \
+               request.referrer or \
+               url_for('index')
+
+As you can see, it accesses the request object.  If you try to run this
+from a plain Python shell, this is the exception you will see:
+
+>>> redirect_url()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+AttributeError: 'NoneType' object has no attribute 'request'
+
+That makes a lot of sense because we currently do not have a request we
+could access.  So we have to make a request and bind it to the current
+context.  The :attr:`~flask.Flask.test_request_context` method can create
+us a request context:
+
+>>> ctx = app.test_request_context('/?next=http://example.com/')
+
+This context can be used in two ways.  Either with the `with` statement
+(which unfortunately is not very handy for shell sessions).  The
+alternative way is to call the `push` and `pop` methods:
+
+>>> ctx.push()
+
+From that point onwards you can work with the request object:
+
+>>> redirect_url()
+u'http://example.com/'
+
+Until you call `pop`:
+
+>>> ctx.pop()
+>>> redirect_url()
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+AttributeError: 'NoneType' object has no attribute 'request'
+
+
+Firing Before/After Request
+---------------------------
+
+By just creating a request context, you still don't have run the code that
+is normally run before a request.  This probably results in your database
+being unavailable, the current user not being stored on the
+:data:`~flask.g` object etc.
+
+This however can easily be done yourself.  Just call
+:meth:`~flask.Flask.preprocess_request`:
+
+>>> ctx = app.test_request_context()
+>>> ctx.push()
+>>> app.preprocess_request()
+
+Keep in mind that the :meth:`~flask.Flask.preprocess_request` function
+might return a response object, in that case just ignore it.
+
+To shutdown a request, you need to trick a bit before the after request
+functions (triggered by :meth:`~flask.Flask.process_response`) operate on
+a response object:
+
+>>> app.process_response(app.response_class())
+<Response 0 bytes [200 OK]>
+>>> ctx.pop()
+
+
+Further Improving the Shell Experience
+--------------------------------------
+
+If you like the idea of experimenting in a shell, create yourself a module
+with stuff you want to star import into your interactive session.  There
+you could also define some more helper methods for common things such as
+initializing the database, dropping tables etc.
+
+Just put them into a module (like `shelltools` and import from there):
+
+>>> from shelltools import *
