Breaking docs up into smaller pieces

docs/patterns/packages.rst

@@ -0,0 +1,87 @@
+.. _larger-applications:
+
+Larger Applications
+===================
+
+For larger applications it's a good idea to use a package instead of a
+module.  That is quite simple.  Imagine a small application looks like
+this::
+
+    /yourapplication
+        /yourapplication.py
+        /static
+            /style.css
+        /templates
+            layout.html
+            index.html
+            login.html
+            ...
+
+To convert that into a larger one, just create a new folder
+`yourapplication` inside the existing one and move everything below it.
+Then rename `yourapplication.py` to `__init__.py`.  (Make sure to delete
+all `.pyc` files first, otherwise things would most likely break)
+
+You should then end up with something like that::
+
+    /yourapplication
+        /yourapplication
+            /__init__.py
+            /static
+                /style.css
+            /templates
+                layout.html
+                index.html
+                login.html
+                ...
+
+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 `runserver.py` next to the inner
+`yourapplication` folder with the following contents::
+
+    from yourapplication import app
+    app.run(debug=True)
+
+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
+following quick checklist:
+
+1. the `Flask` application object creation have to be in the
+   `__init__.py` file.  That way each module can import it safely and the
+   `__name__` variable will resole to the correct package.
+2. all the view functions (the ones with a :meth:`~flask.Flask.route`
+   decorator on top) have to be imported when in the `__init__.py` file.
+   Not the objects itself, but the module it is in.  Do the importing at
+   the *bottom* of the file.
+
+Here an example `__init__.py`::
+
+    from flask import Flask
+    app = Flask(__name__)
+
+    import yourapplication.views
+
+And this is what `views.py` would look like::
+
+    from yourapplication import app
+
+    @app.route('/')
+    def index():
+        return 'Hello World!'
+
+.. admonition:: Circular Imports
+
+   Every Python programmer hates them, and yet we just added some:
+   circular imports (That's when two module depend on each one.  In this
+   case `views.py` depends on `__init__.py`).  Be advised that this is a
+   bad idea in general but here it is actually fine.  The reason for this
+   is
+   that we are not actually using the views in `__init__.py` and just
+   ensuring the module is imported and we are doing that at the bottom of
+   the file.
+
+   There are still some problems with that approach but if you want to use
+   decorators there is no way around that.  Check out the
+   :ref:`becomingbig` section for some inspiration how to deal with that.