From 59104db2f2f0a507aea2625230e446361e2fc174 Mon Sep 17 00:00:00 2001
From: Kyle Lawlor <wgwz@users.noreply.github.com>
Date: Sun, 11 Sep 2016 11:53:35 -0400
Subject: [PATCH] Address #1980 (#2021)

* Distinguish between directories and files

* Convert larger apps to make use of setup.py

- replaces runserver.py with setup.py
- example now runs with recommended structure

* Fixes a typo and formats the added paragraph
---
 docs/patterns/packages.rst | 47 +++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 11 deletions(-)

diff --git a/docs/patterns/packages.rst b/docs/patterns/packages.rst
index af51717d..1cd77974 100644
--- a/docs/patterns/packages.rst
+++ b/docs/patterns/packages.rst
@@ -8,9 +8,9 @@ module.  That is quite simple.  Imagine a small application looks like
 this::
 
     /yourapplication
-        /yourapplication.py
+        yourapplication.py
         /static
-            /style.css
+            style.css
         /templates
             layout.html
             index.html
@@ -29,9 +29,9 @@ You should then end up with something like that::
 
     /yourapplication
         /yourapplication
-            /__init__.py
+            __init__.py
             /static
-                /style.css
+                style.css
             /templates
                 layout.html
                 index.html
@@ -41,11 +41,36 @@ You should then end up with something like that::
 But how do you run your application now?  The naive ``python
 yourapplication/__init__.py`` will not work.  Let's just say that Python
 does not want modules in packages to be the startup file.  But that is not
-a big problem, just add a new file called :file:`runserver.py` next to the inner
+a big problem, just add a new file called :file:`setup.py` next to the inner
 :file:`yourapplication` folder with the following contents::
 
-    from yourapplication import app
-    app.run(debug=True)
+    from setuptools import setup
+
+    setup(
+        name='yourapplication',
+        packages=['yourapplication'],
+        include_package_data=True,
+        install_requires=[
+            'flask',
+        ],
+    )
+
+In order to run the application you need to export an environment variable 
+that tells Flask where to find the application instance:: 
+
+    export FLASK_APP=yourapplication
+
+If you are outside of the project directory make sure to provide the exact 
+path to your application directory. Similiarly you can turn on "debug 
+mode" with this environment variable:: 
+
+    export FLASK_DEBUG=true 
+
+In order to install and run the application you need to issue the following 
+commands::
+
+    pip install -e . 
+    flask run
 
 What did we gain from this?  Now we can restructure the application a bit
 into multiple modules.  The only thing you have to remember is the
@@ -77,12 +102,12 @@ And this is what :file:`views.py` would look like::
 You should then end up with something like that::
 
     /yourapplication
-        /runserver.py
+        setup.py
         /yourapplication
-            /__init__.py
-            /views.py
+            __init__.py
+            views.py
             /static
-                /style.css
+                style.css
             /templates
                 layout.html
                 index.html