Updated docs for click support

docs/contents.rst.inc

@@ -23,6 +23,8 @@ instructions for web development with Flask.
    reqcontext
    blueprints
    extensions
+   cli
+   server
    shell
    patterns/index
    deploying/index

docs/quickstart.rst

@@ -20,16 +20,19 @@ A minimal Flask application looks something like this::
     def hello_world():
         return 'Hello World!'
 
-    if __name__ == '__main__':
-        app.run()
-
 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::
 
-    $ python hello.py
+    $ 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
@@ -51,10 +54,8 @@ 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 :meth:`~flask.Flask.run` function to run the local server
+5. Finally we use the Flask development server to run the local server
-   with our application.  The ``if __name__ == '__main__':`` makes sure the
+   with our application.
-   server only runs if the script is executed directly from the Python
-   interpreter and not used as an imported module.
 
 To stop the server, hit control-C.
 
@@ -67,37 +68,73 @@ To stop the server, hit control-C.
    default because in debugging mode a user of the application can execute
    arbitrary Python code on your computer.
 
-   If you have `debug` disabled or trust the users on your network, you can
+   If you have the debugger disabled or trust the users on your network,
-   make the server publicly available simply by changing the call of the
+   you can make the server publicly available simply by adding
-   :meth:`~flask.Flask.run` method to look like this::
+   ``--host=0.0.0.0`` to the command line::
 
-       app.run(host='0.0.0.0')
+       flask -a hello run --host=0.0.0.0
 
    This tells your operating system to listen on all public IPs.
 
+What to do if the Server does not Start
+---------------------------------------
+
+In case the ``python -m flask`` fails or ``flask`` does not exist,
+there are multiple reasons this might be the case.  First of all you need
+to look at the error message.
+
+Old Version of Flask
+````````````````````
+
+Versions of Flask older than 1.0 use to have different ways to start the
+application.  In short, the ``flask`` command did not exist, and
+neither did ``python -m flask``.  In that case you have two options:
+either upgrade to newer Flask versions or have a look at the :ref:`server`
+docs to see the alternative method for running a server.
+
+Python older 2.7
+````````````````
+
+In case you have a version of Python older than 2.7 ``python -m flask``
+does not work.  You can either use ``flask`` or ``python -m
+flask.cli`` as an alternative.  This is because Python before 2.7 does no
+permit packages to act as executable modules.  For more information see
+:ref:`cli`.
+
+Invalid Import Name
+```````````````````
+
+The ``-a`` argument to ``flask`` is the name of the module to import.  In
+case that module is incorrectly named you will get an import error upon
+start (or if debug is enabled when you navigate to the application).  It
+will tell you what it tried to import and why it failed.
+
+The most common reason is a typo or because you did not actually create an
+``app`` object.
 
 .. _debug-mode:
 
 Debug Mode
 ----------
 
-The :meth:`~flask.Flask.run` method is nice to start a local
+The ``flask`` script is nice to start a local development server, but
-development server, but you would have to restart it manually after each
+you would have to restart it manually after each change to your code.
-change to your code.  That is not very nice and Flask can do better.  If
+That is not very nice and Flask can do better.  If you enable debug
-you enable debug support the server will reload itself on code changes,
+support the server will reload itself on code changes, and it will also
-and it will also provide you with a helpful debugger if things go wrong.
+provide you with a helpful debugger if things go wrong.
 
-There are two ways to enable debugging.  Either set that flag on the
+There are different ways to enable the debug mode.  The most obvious one
-application object::
+is the ``--debug`` parameter to the ``flask`` command::
 
-    app.debug = True
+    flask --debug -a hello run
-    app.run()
 
-Or pass it as a parameter to run::
+This does the following things:
 
-    app.run(debug=True)
+1.  it activates the debugger
+2.  it activates the automatic reloader
+3.  it enables the debug mode on the Flask application.
 
-Both methods have the exact same effect.
+There are more parameters that are explained in the :ref:`server` docs.
 
 .. admonition:: Attention
 
@@ -236,9 +273,9 @@ below.  It tells Flask to behave as though it is handling a request, even
 though we are interacting with it through a Python shell.  Have a look at the
 explanation below. :ref:`context-locals`).
 
-Why would you want to build URLs using the URL reversing function :func:`~flask.url_for` 
+Why would you want to build URLs using the URL reversing function
-instead of hard-coding them into your templates?  There are three good reasons 
+:func:`~flask.url_for` instead of hard-coding them into your templates?
-for this:
+There are three good reasons for this:
 
 1. Reversing is often more descriptive than hard-coding the URLs.  More
    importantly, it allows you to change URLs in one go, without having to

docs/server.rst

@@ -0,0 +1,50 @@
+.. _server:
+
+Development Server
+==================
+
+.. currentmodule:: flask
+
+Starting with Flask 1.0 there are multiple built-in ways to run a
+development server.  The best one is the ``flask`` command line utility
+but you can also continue using the :meth:`Flask.run` method.
+
+Command Line
+------------
+
+The ``flask`` command line script (:ref:`cli`) is strongly recommende for
+development because it provides a superior reload experience due to how it
+loads the application.  The basic usage is like this::
+
+    $ flask -a my_application --debug run
+
+This will enable the debugger, the reloader and then start the server on 
+*http://localhost:5000/*.
+
+The individual features of the server can be controlled by passing more
+arguments to the ``run`` option.  For instance the reloader can be
+disabled::
+
+    $ flask -a my_application --debug run --no-reload
+
+In Code
+-------
+
+The alternative way to start the application is through the
+:meth:`Flask.run` method.  This will immediately launch a local server
+exactly the same way the ``flask`` script does.
+
+Example::
+
+    if __name__ == '__main__':
+        app.run()
+
+This works well for the common case but it does not work well for
+development which is why from Flask 1.0 onwards the ``flask`` method is
+recommended.  The reason for this is that due to how the reload mechanism
+works there are some bizarre side-effects (like executing certain code
+twice, sometimes crashing without message or dieing when a syntax or
+import error happens).
+
+It is however still a perfectly valid method for invoking a non automatic
+reloading application.

docs/shell.rst

@@ -26,6 +26,16 @@ context.
 Generally it's recommended that you read the :ref:`request-context`
 chapter of the documentation first.
 
+Command Line Interface
+----------------------
+
+Starting with Flask 1.0 the recommended way to work with the shell is the
+``flask shell`` command which does a lot of this automatically for you.
+For instance the shell is automatically initialized with a loaded
+application context.
+
+For more information see :ref:`cli`.
+
 Creating a Request Context
 --------------------------