Clean up tutorial docs for installable app pattern with flaskr (#2002)

* Clean up tutorial docs for installable app pattern

- reading sequentially through the tutorial works.
- fixes references to `export FLASK_APP=flaskr.flaskr`

* Fixes titles for each section of flaskr tutorial

* Revert grammar

* Emphasize the Packaging Guide

- adds more general packaging resource
- removes the emphasis put on setuptools

* rephrase and remove note admonitions

- expanded on few points
- removed note blocks, they are unneccessary

* Remove note about reinstalling to update cli

- I had mistakenly thought it was necessary to
  re-install the app to update the cli.
- the `--editable` flag detects the change and
  the cli updates without issue.

docs/tutorial/packaging.rst

@@ -0,0 +1,108 @@
+.. _tutorial-packaging:
+
+Step 3: Installing flaskr as a Package
+======================================
+
+Flask is now shipped with built-in support for `Click`_.  Click provides
+Flask with enhanced and extensible command line utilities.  Later in this
+tutorial you will see exactly how to extend the ``flask`` command line
+interface (CLI).
+
+A useful pattern to manage a Flask application is to install your app
+following the `Python Packaging Guide`_.  Presently this involves 
+creating two new files; :file:`setup.py` and :file:`MANIFEST.in` in the 
+projects root directory.  You also need to add an :file:`__init__.py` 
+file to make the :file:`flaskr/flaskr` directory a package.  After these 
+changes, your code structure should be::
+
+    /flaskr
+        /flaskr
+            __init__.py
+            /static
+            /templates
+            flaskr.py
+            schema.sql
+        setup.py
+        MANIFEST.in
+
+The content of the ``setup.py`` file for ``flaskr`` is:
+
+.. sourcecode:: python
+
+    from setuptools import setup
+
+    setup(
+        name='flaskr',
+        packages=['flaskr'],
+        include_package_data=True,
+        install_requires=[
+            'flask',
+        ],
+    )
+
+When using setuptools, it is also necessary to specify any special files
+that should be included in your package (in the :file:`MANIFEST.in`).
+In this case, the static and templates directories need to be included,
+as well as the schema. Create the :file:`MANIFEST.in` and add the
+following lines::
+
+    graft flaskr/templates
+    graft flaskr/static
+    include flaskr/schema.sql
+
+To simplify locating the application, add the following import statement 
+into this file, :file:`flaskr/__init__.py`:
+
+.. sourcecode:: python
+
+    from flaskr import app
+
+This import statement brings the application instance into the top-level 
+of the application package.  When it is time to run the application, the 
+Flask development server needs the location of the app instance.  This 
+import statement simplifies the location process.  Without it the export 
+statement a few steps below would need to be 
+``export FLASK_APP=flaskr.flaskr``.
+
+At this point you should be able to install the application.  As usual, it
+is recommended to install your Flask application within a `virtualenv`_.
+With that said, go ahead and install the application with::
+
+    pip install --editable .
+
+The above installation command assumes that it is run within the projects 
+root directory, `flaskr/`.  The `editable` flag allows editing 
+source code without having to reinstall the Flask app each time you make 
+changes.  The flaskr app is now installed in your virtualenv (see output 
+of ``pip freeze``).
+
+With that out of the way, you should be able to start up the application.
+Do this with the following commands::
+
+    export FLASK_APP=flaskr
+    export FLASK_DEBUG=true
+    flask run
+
+(In case you are on Windows you need to use `set` instead of `export`).
+The :envvar:`FLASK_DEBUG` flag enables or disables the interactive debugger.
+*Never leave debug mode activated in a production system*, because it will
+allow users to execute code on the server!
+
+You will see a message telling you that server has started along with
+the address at which you can access it.
+
+When you head over to the server in your browser, you will get a 404 error
+because we don't have any views yet.  That will be addressed a little later,
+but first, you should get the database working.
+
+.. admonition:: Externally Visible Server
+
+   Want your server to be publicly available?  Check out the
+   :ref:`externally visible server <public-server>` section for more
+   information.
+
+Continue with :ref:`tutorial-dbcon`.
+
+.. _Click: http://click.pocoo.org
+.. _Python Packaging Guide: https://packaging.python.org
+.. _virtualenv: https://virtualenv.pypa.io