Merge branch 'master' into feature/require-csrf

25 files changed, 97 insertions, 429 deletions

diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst
index 7fd8173d4..cb3839b08 100644
--- a/docs/quick_tutorial/authentication.rst
+++ b/docs/quick_tutorial/authentication.rst
@@ -1,3 +1,5 @@
+.. _qtut_authentication:
+
 ==============================
 20: Logins With Authentication
 ==============================
@@ -33,7 +35,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes authentication; cd authentication
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Put the security hash in the ``authentication/development.ini``
    configuration file as ``tutorial.secret`` instead of putting it in
diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst
index 855043f7f..a4a12774b 100644
--- a/docs/quick_tutorial/authorization.rst
+++ b/docs/quick_tutorial/authorization.rst
@@ -1,3 +1,5 @@
+.. _qtut_authorization:
+
 ===========================================
 21: Protecting Resources With Authorization
 ===========================================
@@ -38,7 +40,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r authentication authorization; cd authorization
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Start by changing ``authorization/tutorial/__init__.py`` to
    specify a root factory to the :term:`configurator`:
diff --git a/docs/quick_tutorial/conf.py b/docs/quick_tutorial/conf.py
deleted file mode 100644
index 47b8fae41..000000000
--- a/docs/quick_tutorial/conf.py
+++ /dev/null
@@ -1,281 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Getting Started with Pyramid and REST documentation build configuration file, created by
-# sphinx-quickstart on Mon Aug 26 14:44:57 2013.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
-# -- General configuration -----------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'Getting Started with Pyramid and REST'
-copyright = u'2013, Agendaless Consulting'
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '1.0'
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'default'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'GettingStartedwithPyramidandRESTdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-    ('index', 'GettingStartedwithPyramidandREST.tex',
-     u'Getting Started with Pyramid and REST Documentation',
-     u'Agendaless Consulting', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
-
-# -- Options for manual page output --------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    ('index', 'gettingstartedwithpyramidandrest',
-     u'Getting Started with Pyramid and REST Documentation',
-     [u'Agendaless Consulting'], 1)
-]
-
-# If true, show URL addresses after external links.
-#man_show_urls = False
-
-
-# -- Options for Texinfo output ------------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    ('index', 'GettingStartedwithPyramidandREST',
-     u'Getting Started with Pyramid and REST Documentation',
-     u'Agendaless Consulting', 'GettingStartedwithPyramidandREST',
-     'One line description of project.',
-     'Miscellaneous'),
-]
-
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {
-    'python': (
-        'http://docs.python.org/2',
-        None),
-    'sqla': (
-        'http://docs.sqlalchemy.org/en/latest',
-        None),
-    'pyramid': (
-        'http://docs.pylonsproject.org/projects/pyramid/en/latest/',
-        None),
-    'jinja2': (
-        'http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/',
-        None),
-    'toolbar': (
-        'http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest',
-        None),
-    'deform': (
-        'http://docs.pylonsproject.org/projects/deform/en/latest',
-        None),
-    'colander': (
-        'http://docs.pylonsproject.org/projects/colander/en/latest',
-        None),
-    'tutorials': (
-        'http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/',
-        None),
-}
diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst
index 19dfd066d..f9f548585 100644
--- a/docs/quick_tutorial/databases.rst
+++ b/docs/quick_tutorial/databases.rst
@@ -53,7 +53,7 @@ Steps
 
    .. note::
 
-     We aren't yet doing ``$VENV/bin/python setup.py develop`` as we
+     We aren't yet doing ``$VENV/bin/pip install -e .`` as we
      will change it later.
 
 #. Our configuration file at ``databases/development.ini`` wires
@@ -78,7 +78,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. The script references some models in ``databases/tutorial/models.py``:
 
@@ -176,7 +176,7 @@ module.
 
 The ``initialize_tutorial_db`` is a nice example of framework support.
 You point your setup at the location of some ``[console_scripts]`` and
-these get generated into your virtualenv's ``bin`` directory. Our
+these get generated into your virtual environment's ``bin`` directory. Our
 console script follows the pattern of being fed a configuration file
 with all the bootstrapping. It then opens SQLAlchemy and creates the
 root of the wiki, which also makes the SQLite file. Note the
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index f11abc493..1f89cd319 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -4,8 +4,7 @@
 04: Easier Development with ``debugtoolbar``
 ============================================
 
-Error-handling and introspection using the ``pyramid_debugtoolbar``
-add-on.
+Error handling and introspection using the ``pyramid_debugtoolbar`` add-on.
 
 Background
 ==========
@@ -36,8 +35,8 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
-    $ $VENV/bin/python setup.py develop
-    $ $VENV/bin/easy_install pyramid_debugtoolbar
+    $ $VENV/bin/pip install -e .
+    $ $VENV/bin/pip install pyramid_debugtoolbar
 
 #. Our ``debugtoolbar/development.ini`` gets a configuration entry for
    ``pyramid.includes``:
diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst
index f81b88fc2..023e7127f 100644
--- a/docs/quick_tutorial/forms.rst
+++ b/docs/quick_tutorial/forms.rst
@@ -50,7 +50,7 @@ Steps
 
    .. code-block:: bash
 
-      $ $VENV/bin/python setup.py develop
+      $ $VENV/bin/pip install -e .
 
 #. Register a static view in ``forms/tutorial/__init__.py`` for
    Deform's CSS/JS etc. as well as our demo wikipage scenario's
diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst
index 6f1544e79..b8aa7e87d 100644
--- a/docs/quick_tutorial/functional_testing.rst
+++ b/docs/quick_tutorial/functional_testing.rst
@@ -34,8 +34,8 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r unit_testing functional_testing; cd functional_testing
-    $ $VENV/bin/python setup.py develop
-    $ $VENV/bin/easy_install webtest
+    $ $VENV/bin/pip install -e .
+    $ $VENV/bin/pip install webtest
 
 #. Let's extend ``functional_testing/tutorial/tests.py`` to include a
    functional test:
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index 4ae80ca87..fb661e9c5 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -5,7 +5,7 @@
 ================================
 
 What's the simplest way to get started in Pyramid? A single-file module.
-No Python packages, no ``setup.py``, no other machinery.
+No Python packages, no ``pip install -e .``, no other machinery.
 
 Background
 ==========
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index 36942c767..0aed304df 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -50,7 +50,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Let's make a file ``ini/development.ini`` for our configuration:
 
diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst
index 2121803f9..6b9d5feba 100644
--- a/docs/quick_tutorial/jinja2.rst
+++ b/docs/quick_tutorial/jinja2.rst
@@ -26,8 +26,8 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes jinja2; cd jinja2
-    $ $VENV/bin/python setup.py develop
-    $ $VENV/bin/easy_install pyramid_jinja2
+    $ $VENV/bin/pip install -e .
+    $ $VENV/bin/pip install pyramid_jinja2
 
 #. We need to include ``pyramid_jinja2`` in
    ``jinja2/tutorial/__init__.py``:
diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst
index aa789d833..49421829b 100644
--- a/docs/quick_tutorial/json.rst
+++ b/docs/quick_tutorial/json.rst
@@ -31,7 +31,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes json; cd json
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. We add a new route for ``hello_json`` in
    ``json/tutorial/__init__.py``:
diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst
index 5d29cd196..556a09bf0 100644
--- a/docs/quick_tutorial/logging.rst
+++ b/docs/quick_tutorial/logging.rst
@@ -35,7 +35,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes logging; cd logging
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Extend ``logging/tutorial/views.py`` to log a message:
 
diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst
index afbb7cc3a..fb97cceb2 100644
--- a/docs/quick_tutorial/more_view_classes.rst
+++ b/docs/quick_tutorial/more_view_classes.rst
@@ -57,7 +57,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r templating more_view_classes; cd more_view_classes
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Our route in ``more_view_classes/tutorial/__init__.py`` needs some
    replacement patterns:
diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst
index 54a6a0bd9..6a379032e 100644
--- a/docs/quick_tutorial/package.rst
+++ b/docs/quick_tutorial/package.rst
@@ -14,39 +14,34 @@ namespaced unit called a :ref:`package <python:tut-packages>`. If a
 directory is on ``sys.path`` and has a special file named
 ``__init__.py``, it is treated as a Python package.
 
-Packages can be bundled up, made available for installation,
-and installed through a (muddled, but improving) toolchain oriented
-around a ``setup.py`` file for a
-`setuptools project <http://pythonhosted.org/setuptools/setuptools.html>`_.
-Explaining it all in this
-tutorial will induce madness. For this tutorial, this is all you need to
-know:
+Packages can be bundled up, made available for installation, and installed
+through a toolchain oriented around a ``setup.py`` file. For this tutorial,
+this is all you need to know:
 
-- We will have a directory for each tutorial step as a setuptools *project*
+- We will have a directory for each tutorial step as a *project*.
 
-- This project will contain a ``setup.py`` which injects the features
-  of the setuptool's project machinery into the directory
+- This project will contain a ``setup.py`` which injects the features of the
+  project machinery into the directory.
 
 - In this project we will make a ``tutorial`` subdirectory into a Python
-  *package* using an ``__init__.py`` Python module file
+  *package* using an ``__init__.py`` Python module file.
 
-- We will run ``python setup.py develop`` to install our project in
-  development mode
+- We will run ``pip install -e .`` to install our project in development mode.
 
 In summary:
 
-- You'll do your development in a Python *package*
+- You'll do your development in a Python *package*.
 
-- That package will be part of a setuptools *project*
+- That package will be part of a *project*.
 
 Objectives
 ==========
 
-- Make a Python "package" directory with an ``__init__.py``
+- Make a Python "package" directory with an ``__init__.py``.
 
-- Get a minimum Python "project" in place by making a ``setup.py``
+- Get a minimum Python "project" in place by making a ``setup.py``.
 
-- Install our ``tutorial`` project in development mode
+- Install our ``tutorial`` project in development mode.
 
 Steps
 =====
@@ -66,7 +61,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
     $ mkdir tutorial
 
 #. Enter the following into ``package/tutorial/__init__.py``:
@@ -107,5 +102,6 @@ of an odd duck.  We would never do this unless we were writing a tutorial that
 tries to capture how this stuff works a step at a time.  It's generally a bad
 idea to run a Python module inside a package directly as a script.
 
-.. seealso:: :ref:`Python Packages <python:tut-packages>`,
-   `setuptools Entry Points <http://pythonhosted.org/setuptools/pkg_resources.html#entry-points>`_
+.. seealso:: :ref:`Python Packages <python:tut-packages>` and `Working in
+   "Development Mode"
+   <https://packaging.python.org/en/latest/distributing/#working-in-development-mode>`_.
diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst
index 4f8de0221..f42423de8 100644
--- a/docs/quick_tutorial/request_response.rst
+++ b/docs/quick_tutorial/request_response.rst
@@ -41,7 +41,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes request_response; cd request_response
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Simplify the routes in ``request_response/tutorial/__init__.py``:
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index f855dcb55..9e10e3ebe 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -4,9 +4,9 @@
 Requirements
 ============
 
-Let's get our tutorial environment setup. Most of the setup work is in
-standard Python development practices (install Python,
-make an isolated environment, and setup packaging tools.)
+Let's get our tutorial environment set up. Most of the set up work is in
+standard Python development practices (install Python and make an isolated
+environment.)
 
 .. note::
 
@@ -19,16 +19,14 @@ make an isolated environment, and setup packaging tools.)
 
 This *Quick Tutorial* is based on:
 
-* **Python 3.3**. Pyramid fully supports Python 3.3+ and Python 2.6+.
-  This tutorial uses **Python 3.3** but runs fine under Python 2.7.
+* **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.6+. This
+  tutorial uses **Python 3.5** but runs fine under Python 2.7.
 
-* **pyvenv**. We believe in virtual environments. For this tutorial,
-  we use Python 3.3's built-in solution, the ``pyvenv`` command.
-  For Python 2.7, you can install ``virtualenv``.
+* **venv**. We believe in virtual environments. For this tutorial, we use
+  Python 3.5's built-in solution ``venv``. For Python 2.7, you can install
+  ``virtualenv``.
 
-* **setuptools and easy_install**. We use
-  `setuptools <https://pypi.python.org/pypi/setuptools/>`_
-  and its ``easy_install`` for package management.
+* **pip**. We use ``pip`` for package management.
 
 * **Workspaces, projects, and packages.** Our home directory
   will contain a *tutorial workspace* with our Python virtual
@@ -46,34 +44,40 @@ This *Quick Tutorial* is based on:
 Steps
 =====
 
-#. :ref:`install-python-3.3-or-greater`
+#. :ref:`install-python-3`
 #. :ref:`create-a-project-directory-structure`
 #. :ref:`set-an-environment-variable`
 #. :ref:`create-a-virtual-environment`
-#. :ref:`install-setuptools-(python-packaging-tools)`
 #. :ref:`install-pyramid`
 
-.. _install-python-3.3-or-greater:
 
-Install Python 3.3 or greater
------------------------------
+.. _install-python-3:
 
-Download the latest standard Python 3.3+ release (not development release)
-from `python.org <https://www.python.org/downloads/>`_.
+Install Python 3
+----------------
 
 Windows and Mac OS X users can download and run an installer.
 
+Download the latest standard Python 3 release (not development release) from
+`python.org <https://www.python.org/downloads/>`_.
+
 Windows users should also install the `Python for Windows extensions
 <http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read the
 ``README.txt`` file at the end of the list of builds, and follow its
 directions. Make sure you get the proper 32- or 64-bit build and Python
 version.
 
-Linux users can either use their package manager to install Python 3.3
-or may `build Python 3.3 from source
+Linux users can either use their package manager to install Python 3
+or may `build Python 3 from source
 <http://pyramid.readthedocs.org/en/master/narr/install.html#package-manager-
 method>`_.
 
+.. seealso:: See also :ref:`For Mac OS X Users <for-mac-os-x-users>`, :ref:`If
+   You Don't Yet Have a Python Interpreter (UNIX)
+   <if-you-don-t-yet-have-a-python-interpreter-unix>`, and :ref:`If You Don't
+   Yet Have a Python Interpreter (Windows)
+   <if-you-don-t-yet-have-a-python-interpreter-windows>`.
+
 
 .. _create-a-project-directory-structure:
 
@@ -125,7 +129,7 @@ order to avoid spaces in any of the path names.
 Next within ``projects`` is your workspace directory, here named
 ``quick_tutorial``. A workspace is a common term used by integrated
 development environments (IDE) like PyCharm and PyDev that stores
-isolated Python environments (virtualenvs) and specific project files
+isolated Python environments (virtual environments) and specific project files
 and repositories.
 
 
@@ -142,6 +146,8 @@ environment. We set an environment variable to save typing later.
     # Mac and Linux
     $ export VENV=~/projects/quick_tutorial/env
 
+.. code-block:: ps1con
+
     # Windows
     # TODO: This command does not work
     c:\> set VENV=c:\projects\quick_tutorial\env
@@ -152,62 +158,23 @@ environment. We set an environment variable to save typing later.
 Create a Virtual Environment
 ----------------------------
 
-.. warning:: The current state of isolated Python environments using
-    ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux.  See
-    http://stackoverflow.com/q/15981111/95735 for a discussion of the issue
-    and `PEP 453 <http://www.python.org/dev/peps/pep-0453/>`_ for a proposed
-    resolution.
-
-``pyvenv`` is a tool to create isolated Python 3.3 environments, each
-with its own Python binary and independent set of installed Python
-packages in its site directories. Let's create one, using the location
-we just specified in the environment variable.
+``venv`` is a tool to create isolated Python 3 environments, each with its own
+Python binary and independent set of installed Python packages in its site
+directories. Let's create one, using the location we just specified in the
+environment variable.
 
 .. code-block:: bash
 
     # Mac and Linux
-    $ pyvenv $VENV
-
-    # Windows
-    c:\> c:\Python33\python -m venv %VENV%
-
-.. seealso:: See also Python 3's :mod:`venv module <python3:venv>`,
-   Python 2's `virtualenv <http://www.virtualenv.org/en/latest/>`_
-   package,
-   :ref:`Installing Pyramid on a Windows System <installing_windows>`
-
-
-.. _install-setuptools-(python-packaging-tools):
-
-Install ``setuptools`` (Python packaging tools)
------------------------------------------------
-
-The following command will download a script to install ``setuptools``, then
-pipe it to your environment's version of Python.
-
-.. code-block:: bash
+    $ python3 -m venv $VENV
 
-    # Mac and Linux
-    $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
+.. code-block:: ps1con
 
     # Windows
-    #
-    # Use your web browser to download this file:
-    #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-    #
-    # ...and save it to:
-    # c:\projects\quick_tutorial\ez_setup.py
-    #
-    # Then run the following command:
-
-    c:\> %VENV%\Scripts\python ez_setup.py
-
-If ``wget`` complains with a certificate error, then run this command instead:
+    c:\> c:\Python35\python3 -m venv %VENV%
 
-.. code-block:: bash
-
-    # Mac and Linux
-    $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python
+.. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
+   2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
 
 
 .. _install-pyramid:
@@ -221,10 +188,10 @@ part is pretty easy:
 .. parsed-literal::
 
     # Mac and Linux
-    $ $VENV/bin/easy_install "pyramid==\ |release|\ "
+    $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
     # Windows
-    c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ "
+    c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 Our Python virtual environment now has the Pyramid software available.
 
@@ -234,30 +201,12 @@ during this tutorial:
 .. code-block:: bash
 
     # Mac and Linux
-    $ $VENV/bin/easy_install nose webtest deform sqlalchemy \
+    $ $VENV/bin/pip install nose webtest deform sqlalchemy \
        pyramid_chameleon pyramid_debugtoolbar waitress \
        pyramid_tm zope.sqlalchemy
 
-    # Windows
-    c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy
-
-
-.. note::
+.. code-block:: ps1con
 
-    Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace
-    packages, for which ``pip``'s support is less-than-optimal. Also, Pyramid's
-    dependencies use some optional C extensions for performance:   with
-    ``easy_install``, Windows users can get these extensions without needing
-    a C compiler (``pip`` does not support installing binary Windows
-    distributions, except for ``wheels``, which are not yet available for
-    all dependencies).
-
-.. seealso:: See also :ref:`installing_unix`. For instructions to set up your
-    Python environment for development using Windows or Python 2, see Pyramid's
-    :ref:`Before You Install <installing_chapter>`.
-
-    See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools
-    installation instructions
-    <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_,
-    and `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_.
+    # Windows
+    c:\> %VENV%\Scripts\pip install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy
 
diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst
index 416a346fa..7b6d0904d 100644
--- a/docs/quick_tutorial/routing.rst
+++ b/docs/quick_tutorial/routing.rst
@@ -48,7 +48,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes routing; cd routing
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Our ``routing/tutorial/__init__.py`` needs a route with a replacement
    pattern:
diff --git a/docs/quick_tutorial/scaffolds.rst b/docs/quick_tutorial/scaffolds.rst
index 4f2694100..319eb9d90 100644
--- a/docs/quick_tutorial/scaffolds.rst
+++ b/docs/quick_tutorial/scaffolds.rst
@@ -12,7 +12,7 @@ Background
 ==========
 
 We're going to cover a lot in this tutorial, focusing on one topic at a
-time and writing everything from scratch. As a warmup, though,
+time and writing everything from scratch. As a warm up, though,
 it sure would be nice to see some pixels on a screen.
 
 Like other web development frameworks, Pyramid provides a number of
@@ -47,21 +47,22 @@ Steps
 
         $ $VENV/bin/pcreate --scaffold starter scaffolds
 
-#. Use normal Python development to setup our project for development:
+#. Install our project in editable mode for development in the current
+   directory:
 
     .. code-block:: bash
 
         $ cd scaffolds
-        $ $VENV/bin/python setup.py develop
+        $ $VENV/bin/pip install -e .
 
-#. Startup the application by pointing Pyramid's ``pserve`` command at
+#. Start up the application by pointing Pyramid's ``pserve`` command at
    the project's (generated) configuration file:
 
     .. code-block:: bash
 
         $ $VENV/bin/pserve development.ini --reload
 
-   On startup, ``pserve`` logs some output:
+   On start up, ``pserve`` logs some output:
 
     .. code-block:: bash
 
diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst
index f97405500..06176f2b6 100644
--- a/docs/quick_tutorial/sessions.rst
+++ b/docs/quick_tutorial/sessions.rst
@@ -34,7 +34,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes sessions; cd sessions
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Our ``sessions/tutorial/__init__.py`` needs a choice of session
    factory to get registered with the :term:`configurator`:
diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst
index 3a7496ec7..61c5fbd50 100644
--- a/docs/quick_tutorial/static_assets.rst
+++ b/docs/quick_tutorial/static_assets.rst
@@ -23,7 +23,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r view_classes static_assets; cd static_assets
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. We add a call ``config.add_static_view`` in
    ``static_assets/tutorial/__init__.py``:
diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst
index cf56d2a96..a975d9ec2 100644
--- a/docs/quick_tutorial/templating.rst
+++ b/docs/quick_tutorial/templating.rst
@@ -56,7 +56,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. We need to connect ``pyramid_chameleon`` as a renderer by making a
    call in the setup of ``templating/tutorial/__init__.py``:
diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst
index 204d388b0..8298a4710 100644
--- a/docs/quick_tutorial/tutorial_approach.rst
+++ b/docs/quick_tutorial/tutorial_approach.rst
@@ -17,7 +17,7 @@ repo, where each step/topic/directory is a Python package.
 To successfully run each step::
 
   $ cd request_response
-  $ $VENV/bin/python setup.py develop
+  $ $VENV/bin/pip install -e .
 
 ...and repeat for each step you would like to work on. In most cases we
 will start with the results of an earlier step.
diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst
index 4cb7ef714..58512d1cc 100644
--- a/docs/quick_tutorial/unit_testing.rst
+++ b/docs/quick_tutorial/unit_testing.rst
@@ -48,8 +48,8 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
-    $ $VENV/bin/python setup.py develop
-    $ $VENV/bin/easy_install nose
+    $ $VENV/bin/pip install -e .
+    $ $VENV/bin/pip install nose
 
 #. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:
 
diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst
index 6198eed63..cc5337493 100644
--- a/docs/quick_tutorial/view_classes.rst
+++ b/docs/quick_tutorial/view_classes.rst
@@ -41,7 +41,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r templating view_classes; cd view_classes
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Our ``view_classes/tutorial/views.py`` now has a view class with
    our two views:
diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst
index 6728925fd..5b6e2960b 100644
--- a/docs/quick_tutorial/views.rst
+++ b/docs/quick_tutorial/views.rst
@@ -43,7 +43,7 @@ Steps
    .. code-block:: bash
 
     $ cd ..; cp -r functional_testing views; cd views
-    $ $VENV/bin/python setup.py develop
+    $ $VENV/bin/pip install -e .
 
 #. Our ``views/tutorial/__init__.py`` gets a lot shorter: