Rewrite deployment docs

docs/deploying/index.rst

@@ -3,18 +3,33 @@
 Deployment Options
 ==================
 
-Depending on what you have available there are multiple ways to run
-Flask applications.  You can use the builtin server during development,
-but you should use a full deployment option for production applications.
-(Do not use the builtin development server in production.)  Several
-options are available and documented here.
+Flask's builtin server is lightweight and easy to use, but it has multiple
+problems which you don't want to face in production. With default settings, it
+can handle only one request at a time, and even if you manage to circumvent
+this problem, it has too many scaling problems that would make it unsuitable
+for production. **Do not use the builtin development server in production**.
+Some of the options available for properly running Flask in production are
+documented here.
 
-If you have a different WSGI server look up the server documentation
-about how to use a WSGI app with it.  Just remember that your
-:class:`Flask` application object is the actual WSGI application.
+If you want to deploy your Flask application to a WSGI server not listed here,
+look up the server documentation about how to use a WSGI app with it.  Just
+remember that your :class:`Flask` application object is the actual WSGI
+application.
 
-For hosted options to get up and running quickly, see
-:ref:`quickstart_deployment` in the Quickstart.
+
+Hosted options
+--------------
+
+- `Deploying Flask on Heroku <https://devcenter.heroku.com/articles/getting-started-with-python>`_
+- `Deploying WSGI on dotCloud <http://docs.dotcloud.com/services/python/>`_
+  with `Flask-specific notes <http://flask.pocoo.org/snippets/48/>`_
+- `Deploying Flask on Webfaction <http://flask.pocoo.org/snippets/65/>`_
+- `Deploying Flask on Google App Engine <https://github.com/kamalgill/flask-appengine-template>`_
+- `Sharing your Localhost Server with Localtunnel <http://flask.pocoo.org/snippets/89/>`_
+
+
+Self-hosted options
+-------------------
 
 .. toctree::
    :maxdepth: 2

docs/quickstart.rst

@@ -20,25 +20,7 @@ A minimal Flask application looks something like this::
     def hello_world():
         return 'Hello World!'
 
-Just save it as `hello.py` (or something similar) and run it with your Python
-interpreter.  Make sure to not call your application `flask.py` because this
-would conflict with Flask itself.
-
-To run the application you can either use the ``flask`` command or
-python's ``-m`` switch with Flask::
-
-    $ flask -a hello run
-     * Running on http://127.0.0.1:5000/
-
-or alternatively::
-
-    $ python -m flask -a hello run
-     * Running on http://127.0.0.1:5000/
-
-Now head over to `http://127.0.0.1:5000/ <http://127.0.0.1:5000/>`_, and you
-should see your hello world greeting.
-
-So what did that code do?
+So what does that code do?
 
 1. First we imported the :class:`~flask.Flask` class.  An instance of this
    class will be our WSGI application.
@@ -54,10 +36,27 @@ So what did that code do?
 4. The function is given a name which is also used to generate URLs for that
    particular function, and returns the message we want to display in the
    user's browser.
-5. Finally we use the Flask development server to run the local server
-   with our application.
 
-To stop the server, hit control-C.
+Just save it as `hello.py` (or something similar).  Make sure to not call your
+application `flask.py` because this would conflict with Flask itself.
+
+To run the application you can either use the ``flask`` command or
+python's ``-m`` switch with Flask::
+
+    $ flask -a hello run
+     * Running on http://127.0.0.1:5000/
+
+or alternatively::
+
+    $ python -m flask -a hello run
+     * Running on http://127.0.0.1:5000/
+
+This launches a very simple builtin server, which is good enough for testing
+but probably not what you want to use in production. For deployment options see
+:ref:`deployment`.
+
+Now head over to `http://127.0.0.1:5000/ <http://127.0.0.1:5000/>`_, and you
+should see your hello world greeting. To stop the server, hit control-C.
 
 .. _public-server:
 
@@ -76,6 +75,7 @@ To stop the server, hit control-C.
 
    This tells your operating system to listen on all public IPs.
 
+
 What to do if the Server does not Start
 ---------------------------------------
 
@@ -858,6 +858,8 @@ The attached :attr:`~flask.Flask.logger` is a standard logging
 documentation <https://docs.python.org/library/logging.html>`_ for more
 information.
 
+Read more on :ref:`errorhandling`.
+
 Hooking in WSGI Middlewares
 ---------------------------
 
@@ -869,24 +871,7 @@ can do it like this::
     from werkzeug.contrib.fixers import LighttpdCGIRootFix
     app.wsgi_app = LighttpdCGIRootFix(app.wsgi_app)
 
-.. _quickstart_deployment:
-
 Deploying to a Web Server
 -------------------------
 
-Ready to deploy your new Flask app?  To wrap up the quickstart, you can
-immediately deploy to a hosted platform, all of which offer a free plan for
-small projects:
-
-- `Deploying Flask on Heroku <https://devcenter.heroku.com/articles/getting-started-with-python>`_
-- `Deploying WSGI on dotCloud <http://docs.dotcloud.com/services/python/>`_
-  with `Flask-specific notes <http://flask.pocoo.org/snippets/48/>`_
-
-Other places where you can host your Flask app:
-
-- `Deploying Flask on Webfaction <http://flask.pocoo.org/snippets/65/>`_
-- `Deploying Flask on Google App Engine <https://github.com/kamalgill/flask-appengine-template>`_
-- `Sharing your Localhost Server with Localtunnel <http://flask.pocoo.org/snippets/89/>`_
-
-If you manage your own hosts and would like to host yourself, see the chapter
-on :ref:`deployment`.
+Ready to deploy your new Flask app? Go to :ref:`deployment`.