Address #1902: Converts example/flaskr to have a setup.py (#1945)

* Converts example/flaskr to have a setup.py

Makes the flaskr app easier to run, ex. workflow:
- pip install --editable .
- export FLASK_APP=flaskr.flaskr
- flask initdb
- flask run

Testing is also easier now:
- python setup.py test

* Fixed an import error in flaskr/tests

- the statement `import flaskr` caused errors in python3
- `from . import flaskr` fixes the issue in 2.7.11 and 3.5.1

* Better project structure and updates the docs

- Re-factors *flaskr*'s project structure a bit
- Updates docs to make sense with the new structure
  - Adds a new step about installing Flask apps with setuptools
  - Switches first-person style writing to second-person (reads better IMO)
  - Adds segments in *testing.rst* for running tests with setuptools

* Remove __init__.py from tests

- py.test recommends not using __init__.py

* Fix testing import errors

docs/tutorial/testing.rst

@@ -8,3 +8,81 @@ expected, it's probably not a bad idea to add automated tests to simplify
 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
+======================
+
+Assuming you have seen the testing section above 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.
+
+One possible and recommended project structure is::
+
+    flaskr/
+        flaskr/
+            __init__.py
+            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::
+
+    import sys, os
+
+    basedir = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, basedir + '/../')
+
+    from flaskr import flaskr
+
+Testing + Setuptools
+====================
+
+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::
+
+    from setuptools import setup
+
+    setup(
+        name='flaskr',
+        packages=['flaskr'],
+        include_package_data=True,
+        install_requires=[
+            'flask',
+        ],
+    )
+        setup_requires=[
+            'pytest-runner',
+        ],
+        tests_require=[
+            'pytest',
+        ],
+    )
+Now create :file:`setup.cfg` in the project root (alongside
+:file:`setup.py`)::
+
+    [aliases]
+    test=pytest
+
+Now you can run::
+
+    python setup.py test
+
+This calls on the alias created in :file:`setup.cfg` which in turn runs
+``pytest`` via ``pytest-runner``, as the :file:`setup.py` script has
+been called. (Recall the `setup_requires` argument in :file:`setup.py`)
+Following the standard rules of test-discovery your tests will be
+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.