Merge pull request #2357 from stevepiercy/feature/alchemy-scaffold-update

wiki2 docs update WIP

5 files changed, 87 insertions, 62 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 2683ff369..cbf58c226 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1093,3 +1093,7 @@ Glossary
       A technique used when serving a cacheable static asset in order to force
       a client to query the new version of the asset. See :ref:`cache_busting`
       for more information.
+
+   pip
+      The `Python Packaging Authority <https://www.pypa.io/>`_ recommended tool
+      for installing Python packages.
diff --git a/docs/tutorials/wiki2/background.rst b/docs/tutorials/wiki2/background.rst
index b8afb8305..2dac847d8 100644
--- a/docs/tutorials/wiki2/background.rst
+++ b/docs/tutorials/wiki2/background.rst
@@ -5,13 +5,13 @@ Background
 This version of the :app:`Pyramid` wiki tutorial presents a
 :app:`Pyramid` application that uses technologies which will be
 familiar to someone with SQL database experience.  It uses
-:term:`SQLAlchemy` as a persistence mechanism and :term:`url dispatch` to map
+:term:`SQLAlchemy` as a persistence mechanism and :term:`URL dispatch` to map
 URLs to code.  It can also be followed by people without any prior
 Python web framework experience.
 
 To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
-variant, etc) *or* a Windows system of any kind.
+variant, etc.) *or* a Windows system of any kind.
 
 .. note::
 
diff --git a/docs/tutorials/wiki2/design.rst b/docs/tutorials/wiki2/design.rst
index 45e2fddd0..929bc7806 100644
--- a/docs/tutorials/wiki2/design.rst
+++ b/docs/tutorials/wiki2/design.rst
@@ -10,7 +10,7 @@ Overall
 
 We choose to use :term:`reStructuredText` markup in the wiki text. Translation
 from reStructuredText to HTML is provided by the widely used ``docutils``
-Python module.  We will add this module in the dependency list on the project
+Python module.  We will add this module to the dependency list in the project's
 ``setup.py`` file.
 
 Models
diff --git a/docs/tutorials/wiki2/index.rst b/docs/tutorials/wiki2/index.rst
index 74fb5bfd5..18e9f552e 100644
--- a/docs/tutorials/wiki2/index.rst
+++ b/docs/tutorials/wiki2/index.rst
@@ -1,15 +1,15 @@
 .. _bfg_sql_wiki_tutorial:
 
-SQLAlchemy + URL Dispatch Wiki Tutorial
+SQLAlchemy + URL dispatch wiki tutorial
 =======================================
 
-This tutorial introduces a :term:`SQLAlchemy` and :term:`url dispatch`-based
+This tutorial introduces an :term:`SQLAlchemy` and :term:`URL dispatch`-based
 :app:`Pyramid` application to a developer familiar with Python.  When the
-tutorial is finished, the developer will have created a basic Wiki
-application with authentication.
+tutorial is finished, the developer will have created a basic wiki
+application with authentication and authorization.
 
-For cut and paste purposes, the source code for all stages of this
-tutorial can be browsed on GitHub at `docs/tutorials/wiki2/src
+For cut and paste purposes, the source code for all stages of this tutorial can
+be browsed on GitHub at `docs/tutorials/wiki2/src
 <https://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src>`_,
 which corresponds to the same location if you have Pyramid sources.
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 5d6d8e56b..1dd71cb76 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -9,9 +9,9 @@ This tutorial assumes that you have already followed the steps in
 :ref:`installing_chapter`, except **do not create a virtualenv or install
 Pyramid**.  Thereby you will satisfy the following requirements.
 
-* Python interpreter is installed on your operating system
-* :term:`setuptools` or :term:`distribute` is installed
-* :term:`virtualenv` is installed
+* A Python interpreter is installed on your operating system.
+* :term:`virtualenv` is installed.
+* :term:`pip` will be installed when we create a virtual environment.
 
 Create directory to contain the project
 ---------------------------------------
@@ -21,38 +21,36 @@ We need a workspace for our project files.
 On UNIX
 ^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
     $ mkdir ~/pyramidtut
 
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\> mkdir pyramidtut
 
 Create and use a virtual Python environment
 -------------------------------------------
 
-Next let's create a `virtualenv` workspace for our project.  We will
-use the `VENV` environment variable instead of the absolute path of the
-virtual environment.
+Next let's create a ``virtualenv`` workspace for our project.  We will use the
+``VENV`` environment variable instead of the absolute path of the virtual
+environment.
 
 On UNIX
 ^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
    $ export VENV=~/pyramidtut
    $ virtualenv $VENV
-   New python executable in /home/foo/env/bin/python
-   Installing setuptools.............done.
 
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\> set VENV=c:\pyramidtut
 
@@ -61,15 +59,24 @@ path to the command for your Python version.
 
 Python 2.7:
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\> c:\Python27\Scripts\virtualenv %VENV%
 
-Python 3.3:
+Python 3.5:
 
-.. code-block:: text
+.. code-block:: ps1con
+
+   c:\> c:\Python35\Scripts\virtualenv %VENV%
+
+
+.. Upgrade pip in the virtual environment
+   --------------------------------------
+
+.. .. code-block:: bash
+
+..    $ $VENV/bin/pip install --upgrade pip
 
-   c:\> c:\Python33\Scripts\virtualenv %VENV%
 
 Install Pyramid into the virtual Python environment
 ---------------------------------------------------
@@ -77,52 +84,58 @@ Install Pyramid into the virtual Python environment
 On UNIX
 ^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/easy_install pyramid
 
+..   $ $VENV/bin/pip install pyramid
+
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\> %VENV%\Scripts\easy_install pyramid
 
+..   c:\> %VENV%\Scripts\pip install pyramid
+
 Install SQLite3 and its development packages
 --------------------------------------------
 
 If you used a package manager to install your Python or if you compiled
 your Python from source, then you must install SQLite3 and its
 development packages.  If you downloaded your Python as an installer
-from https://www.python.org, then you already have it installed and can
-proceed to the next section :ref:`sql_making_a_project`.
+from https://www.python.org, then you already have it installed and can skip
+this step.
 
 If you need to install the SQLite3 packages, then, for example, using
 the Debian system and ``apt-get``, the command would be the following:
 
-.. code-block:: text
+.. code-block:: bash
 
    $ sudo apt-get install libsqlite3-dev
 
 Change directory to your virtual Python environment
 ---------------------------------------------------
 
-Change directory to the ``pyramidtut`` directory.
+Change directory to the ``pyramidtut`` directory, which is both your workspace
+and your virtual environment.
 
 On UNIX
 ^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
    $ cd pyramidtut
 
 On Windows
 ^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\> cd pyramidtut
 
+
 .. _sql_making_a_project:
 
 Making a project
@@ -132,30 +145,29 @@ Your next step is to create a project.  For this tutorial we will use
 the :term:`scaffold` named ``alchemy`` which generates an application
 that uses :term:`SQLAlchemy` and :term:`URL dispatch`.
 
-:app:`Pyramid` supplies a variety of scaffolds to generate sample
-projects. We will use `pcreate` — a script that comes with Pyramid to
-quickly and easily generate scaffolds, usually with a single command — to
-create the scaffold for our project.
+:app:`Pyramid` supplies a variety of scaffolds to generate sample projects. We
+will use ``pcreate``, a script that comes with Pyramid, to create our project
+using a scaffold.
 
-By passing `alchemy` into the `pcreate` command, the script creates
-the files needed to use SQLAlchemy. By passing in our application name
-`tutorial`, the script inserts that application name into all the
-required files. For example, `pcreate` creates the
-``initialize_tutorial_db`` in the ``pyramidtut/bin`` directory.
+By passing ``alchemy`` into the ``pcreate`` command, the script creates the
+files needed to use SQLAlchemy. By passing in our application name
+``tutorial``, the script inserts that application name into all the required
+files. For example, ``pcreate`` creates the ``initialize_tutorial_db`` in the
+``pyramidtut/bin`` directory.
 
 The below instructions assume your current working directory is "pyramidtut".
 
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/pcreate -s alchemy tutorial
 
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut> %VENV%\Scripts\pcreate -s alchemy tutorial
 
@@ -165,34 +177,39 @@ On Windows
    startup problems, try putting both the virtualenv and the project
    into directories that do not contain spaces in their paths.
 
+
 .. _installing_project_in_dev_mode:
 
 Installing the project in development mode
 ==========================================
 
-In order to do development on the project easily, you must "register"
-the project as a development egg in your workspace using the
-``setup.py develop`` command.  In order to do so, cd to the `tutorial`
-directory you created in :ref:`sql_making_a_project`, and run the
-``setup.py develop`` command using the virtualenv Python interpreter.
+In order to do development on the project easily, you must "register" the
+project as a development egg in your workspace using the ``setup.py develop``
+command. In order to do so, change directory to the ``tutorial`` directory that
+you created in :ref:`sql_making_a_project`, and run the ``setup.py develop``
+command using the virtualenv Python interpreter.
 
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ cd tutorial
    $ $VENV/bin/python setup.py develop
 
+..   $ $VENV/bin/pip install -e .
+
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut> cd tutorial
    c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
-The console will show `setup.py` checking for packages and installing
+..   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
+
+The console will show ``setup.py`` checking for packages and installing
 missing packages. Success executing this command will show a line like
 the following::
 
@@ -209,17 +226,21 @@ the tests for the project.
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/python setup.py test -q
 
+.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046
+
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
+.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046
+
 For a successful test run, you should see output that ends like this::
 
   .
@@ -243,14 +264,14 @@ To get this functionality working, we'll need to install the ``nose`` and
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/easy_install nose coverage
 
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage
 
@@ -260,14 +281,14 @@ coverage tests.
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
 
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
          --cover-erase --with-coverage
@@ -311,14 +332,14 @@ directory (the directory with a ``development.ini`` in it):
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/initialize_tutorial_db development.ini
 
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
 
@@ -363,14 +384,14 @@ Start the application.
 On UNIX
 -------
 
-.. code-block:: text
+.. code-block:: bash
 
    $ $VENV/bin/pserve development.ini --reload
 
 On Windows
 ----------
 
-.. code-block:: text
+.. code-block:: ps1con
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload