Updated documentation once more for new cli.

docs/cli.rst

@@ -99,3 +99,32 @@ The command will then show up on the command line::
 
     $ flask -a hello.py initdb
     Init the db
+
+Factory Functions
+-----------------
+
+In case you are using factory functions to create your application (see
+:ref:`app-factories`) you will discover that the ``flask`` command cannot
+work with them directly.  Flask won't be able to figure out how to
+instanciate your application properly by itself.  Because of this reason
+the recommendation is to create a separate file that instanciates
+applications.
+
+For instance if you have a factory function that creates an application
+from a filename you could make a separate file that creates such an
+application from an environment variable.
+
+For instance this could be a file named ``autoapp.py`` with these
+contents::
+
+    import os
+    from yourapplication import create_app
+    app = create_app(os.environ['YOURAPPLICATION_CONFIG'])
+
+Once this has happened you can make the flask command automatically pick
+it up::
+
+    export YOURAPPLICATION_CONFIG=/path/to/config.cfg
+    export FLASK_APP=/path/to/autoapp.py
+
+From this point onwards ``flask`` will find your application.

docs/patterns/appfactories.rst

@@ -90,11 +90,16 @@ Using Applications
 ------------------
 
 So to use such an application you then have to create the application
-first.  Here an example `run.py` file that runs such an application::
+first in a separate file otherwise the ``flask`` command won't be able
+to find it.  Here an example `exampleapp.py` file that creates such
+an application::
 
     from yourapplication import create_app
     app = create_app('/path/to/config.cfg')
-    app.run()
+
+It can then be used with the ``flask`` command::
+
+    flask --app=exampleapp run
 
 Factory Improvements
 --------------------

docs/patterns/flashing.rst

@@ -38,10 +38,6 @@ So here is a full example::
                 return redirect(url_for('index'))
         return render_template('login.html', error=error)
 
-    if __name__ == "__main__":
-        app.run()
-
-
 And here the ``layout.html`` template which does the magic:
 
 .. sourcecode:: html+jinja

flask/cli.py

@@ -63,6 +63,11 @@ def prepare_exec_for_file(filename):
         filename = filename[:-3]
     elif os.path.split(filename)[1] == '__init__.py':
         filename = os.path.dirname(filename)
+    else:
+        raise NoAppException('The file provided (%s) does exist but is not a '
+                             'valid Python file.  This means that it cannot '
+                             'be used as application.  Please change the '
+                             'extension to .py' % filename)
     filename = os.path.realpath(filename)
 
     dirpath = filename