Minor edits to tutorial for clarity. (#2330)

docs/tutorial/setup.rst

@@ -3,27 +3,31 @@
 Step 2: Application Setup Code
 ==============================
 
-Now that the schema is in place, you can create the application module,
-:file:`flaskr.py`.  This file should be placed inside of the
-:file:`flaskr/flaskr` folder.  The first several lines of code in the
-application module are the needed import statements.  After that there will be a
-few lines of configuration code. For small applications like ``flaskr``, it is
-possible to drop the configuration directly into the module.  However, a cleaner
-solution is to create a separate ``.ini`` or ``.py`` file, load that, and
-import the values from there.
+Next, we will create the application module, :file:`flaskr.py`.  Just like the
+:file:`schema.sql` file you created in the previous step, this file should be
+placed inside of the :file:`flaskr/flaskr` folder.
+
+For this tutorial, all the Python code we use will be put into this file
+(except for one line in ``__init__.py``, and any testing or optional files you
+decide to create).
+
+The first several lines of code in the application module are the needed import
+statements.  After that there will be a few lines of configuration code.
+
+For small applications like ``flaskr``, it is possible to drop the configuration
+directly into the module.  However, a cleaner solution is to create a separate
+``.py`` file, load that, and import the values from there.
 
 Here are the import statements (in :file:`flaskr.py`)::
 
-    # all the imports
     import os
     import sqlite3
-    from flask import Flask, request, session, g, redirect, url_for, abort, \
-         render_template, flash
+
+    from flask import (Flask, request, session, g, redirect, url_for, abort,
+        render_template, flash)
 
 The next couple lines will create the actual application instance and
-initialize it with the config from the same file in :file:`flaskr.py`:
-
-.. sourcecode:: python
+initialize it with the config from the same file in :file:`flaskr.py`::
 
     app = Flask(__name__) # create the application instance :)
     app.config.from_object(__name__) # load config from this file , flaskr.py
@@ -37,8 +41,8 @@ initialize it with the config from the same file in :file:`flaskr.py`:
     ))
     app.config.from_envvar('FLASKR_SETTINGS', silent=True)
 
-The :class:`~flask.Config` object works similarly to a dictionary, so it can be
-updated with new values.
+In the above code, the :class:`~flask.Config` object works similarly to a
+dictionary, so it can be updated with new values.
 
 .. admonition:: Database Path
 
@@ -58,15 +62,15 @@ updated with new values.
 Usually, it is a good idea to load a separate, environment-specific
 configuration file.  Flask allows you to import multiple configurations and it
 will use the setting defined in the last import.  This enables robust
-configuration setups.  :meth:`~flask.Config.from_envvar` can help achieve this.
-
-.. sourcecode:: python
+configuration setups.  :meth:`~flask.Config.from_envvar` can help achieve
+this. ::
 
    app.config.from_envvar('FLASKR_SETTINGS', silent=True)
 
-Simply define the environment variable :envvar:`FLASKR_SETTINGS` that points to
-a config file to be loaded.  The silent switch just tells Flask to not complain
-if no such environment key is set.
+If you want to do this (not required for this tutorial) simply define the
+environment variable :envvar:`FLASKR_SETTINGS` that points to a config file
+to be loaded.  The silent switch just tells Flask to not complain if no such
+environment key is set.
 
 In addition to that, you can use the :meth:`~flask.Config.from_object`
 method on the config object and provide it with an import name of a
@@ -76,22 +80,22 @@ that in all cases, only variable names that are uppercase are considered.
 The ``SECRET_KEY`` is needed to keep the client-side sessions secure.
 Choose that key wisely and as hard to guess and complex as possible.
 
-Lastly, you will add a method that allows for easy connections to the
-specified database.  This can be used to open a connection on request and
-also from the interactive Python shell or a script.  This will come in
-handy later.  You can create a simple database connection through SQLite and
-then tell it to use the :class:`sqlite3.Row` object to represent rows.
-This allows the rows to be treated as if they were dictionaries instead of
-tuples.
-
-.. sourcecode:: python
+Lastly, add a method that allows for easy connections to the specified
+database. ::
 
     def connect_db():
         """Connects to the specific database."""
+
         rv = sqlite3.connect(app.config['DATABASE'])
         rv.row_factory = sqlite3.Row
         return rv
 
+This can be used to open a connection on request and also from the
+interactive Python shell or a script.  This will come in handy later.
+You can create a simple database connection through SQLite and then tell
+it to use the :class:`sqlite3.Row` object to represent rows. This allows
+the rows to be treated as if they were dictionaries instead of tuples.
+
 In the next section you will see how to run the application.
 
 Continue with :ref:`tutorial-packaging`.