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/css.rst

@@ -1,6 +1,6 @@
 .. _tutorial-css:
 
-Step 9: Adding Style
+Step 8: Adding Style
 ====================
 
 Now that everything else works, it's time to add some style to the

docs/tutorial/dbcon.rst

@@ -3,7 +3,7 @@
 Step 4: Database Connections
 ----------------------------
 
-You now have a function for establishing a database connection with
+You currently have a function for establishing a database connection with
 `connect_db`, but by itself, it is not particularly useful.  Creating and
 closing database connections all the time is very inefficient, so you will
 need to keep it around for longer.  Because database connections

docs/tutorial/index.rst

@@ -24,7 +24,7 @@ the `example source`_.
    folders
    schema
    setup
-   setuptools
+   packaging
    dbcon
    dbinit
    views

docs/tutorial/packaging.rst

@@ -1,7 +1,7 @@
-.. _tutorial-setuptools:
+.. _tutorial-packaging:
 
-Step 3: Installing flaskr with setuptools
-=========================================
+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
@@ -9,17 +9,21 @@ 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
-using `setuptools`_.  This involves creating a :file:`setup.py`
-in the projects root directory.  You also need to add an empty
-:file:`__init__.py` file to make the :file:`flaskr/flaskr` directory
-a package.  The code structure at this point should be::
+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:
 
@@ -46,22 +50,37 @@ following lines::
     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 .
 
-.. note:: The above installation command assumes that it is run within the
-    projects root directory, `flaskr/`.  Also, the `editable` flag allows
-    editing source code without having to reinstall the Flask app each time
-    you make changes.
+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.flaskr
-    export FLASK_DEBUG=1
+    export FLASK_APP=flaskr
+    export FLASK_DEBUG=true
     flask run
 
 (In case you are on Windows you need to use `set` instead of `export`).
@@ -85,5 +104,5 @@ but first, you should get the database working.
 Continue with :ref:`tutorial-dbcon`.
 
 .. _Click: http://click.pocoo.org
-.. _setuptools: https://setuptools.readthedocs.io
+.. _Python Packaging Guide: https://packaging.python.org
 .. _virtualenv: https://virtualenv.pypa.io

docs/tutorial/setup.rst

@@ -94,4 +94,4 @@ tuples.
 
 In the next section you will see how to run the application.
 
-Continue with :ref:`tutorial-setuptools`.
+Continue with :ref:`tutorial-packaging`.

docs/tutorial/templates.rst

@@ -1,6 +1,6 @@
 .. _tutorial-templates:
 
-Step 8: The Templates
+Step 7: The Templates
 =====================
 
 Now it is time to start working on the templates.  As you may have

docs/tutorial/testing.rst

@@ -9,10 +9,10 @@ modifications in the future.  The application above is used as a basic
 example of how to perform unit testing in the :ref:`testing` section of the
 documentation.  Go there to see how easy it is to test Flask applications.
 
-Adding Tests to flaskr
-======================
+Adding tests to flaskr
+----------------------
 
-Assuming you have seen the testing section above and have either written
+Assuming you have seen the :ref:`testing` section and have either written
 your own tests for ``flaskr`` or have followed along with the examples
 provided, you might be wondering about ways to organize the project.
 
@@ -24,30 +24,38 @@ One possible and recommended project structure is::
             static/
             templates/
         tests/
-            context.py
             test_flaskr.py
         setup.py
         MANIFEST.in
 
-For now go ahead a create the :file:`tests/` directory as well as the
-:file:`context.py` and :file:`test_flaskr.py` files, if you haven't
-already. The context file is used as an import helper. The contents
-of that file are::
+For now go ahead a create the :file:`tests/` directory as well as the 
+:file:`test_flaskr.py` file.
 
-    import sys, os
+Running the tests
+-----------------
 
-    basedir = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, basedir + '/../')
+At this point you can run the tests. Here ``pytest`` will be used. 
 
-    from flaskr import flaskr
+.. note:: Make sure that ``pytest`` is installed in the same virtualenv 
+    as flaskr. Otherwise ``pytest`` test will not be able to import the 
+    required components to test the application::
 
-Testing + Setuptools
-====================
+        pip install -e .
+        pip install pytest 
 
-One way to handle testing is to integrate it with ``setuptools``. All it
-requires is adding a couple of lines to the :file:`setup.py` file and
-creating a new file :file:`setup.cfg`. Go ahead and update the
-:file:`setup.py` to contain::
+Run and watch the tests pass, within the top-level :file:`flaskr/` 
+directory as::
+
+    py.test
+
+Testing + setuptools
+--------------------
+
+One way to handle testing is to integrate it with ``setuptools``. Here
+that requires adding a couple of lines to the :file:`setup.py` file and
+creating a new file :file:`setup.cfg`. One benefit of running the tests 
+this way is that you do not have to install ``pytest``. Go ahead and 
+update the :file:`setup.py` file to contain::
 
     from setuptools import setup
 
@@ -58,7 +66,6 @@ creating a new file :file:`setup.cfg`. Go ahead and update the
         install_requires=[
             'flask',
         ],
-    )
         setup_requires=[
             'pytest-runner',
         ],
@@ -66,6 +73,7 @@ creating a new file :file:`setup.cfg`. Go ahead and update the
             'pytest',
         ],
     )
+
 Now create :file:`setup.cfg` in the project root (alongside
 :file:`setup.py`)::
 
@@ -85,4 +93,4 @@ found, run, and hopefully pass.
 This is one possible way to run and manage testing.  Here ``pytest`` is
 used, but there are other options such as ``nose``.  Integrating testing
 with ``setuptools`` is convenient because it is not necessary to actually
-download ``pytest`` or any other testing framework one might use.
+download ``pytest`` or any other testing framework one might use.

docs/tutorial/views.rst

@@ -1,6 +1,6 @@
 .. _tutorial-views:
 
-Step 7: The View Functions
+Step 6: The View Functions
 ==========================
 
 Now that the database connections are working, you can start writing the