Merge pull request #2425 from stevepiercy/docs/easy-install-to-pip.2104

Docs/easy install to pip #2104

3 files changed, 92 insertions, 41 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 9657d9219..ef90a0f41 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -1091,3 +1091,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/quick_tour.rst b/docs/quick_tour.rst
index 65310bf4d..32f049d6a 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -15,28 +15,29 @@ Installation
 
 Once you have a standard Python environment setup, getting started with Pyramid
 is a breeze. Unfortunately "standard" is not so simple in Python. For this
-Quick Tour, it means `Python <https://www.python.org/downloads/>`_, a `virtual
-environment <http://docs.python.org/dev/library/venv.html>`_ (or `virtualenv
-for Python 2.7 <https://pypi.python.org/pypi/virtualenv>`_), and `setuptools
-<https://pypi.python.org/pypi/setuptools/>`_.
+Quick Tour, it means `Python <https://www.python.org/downloads/>`_, `venv
+<https://packaging.python.org/en/latest/projects/#venv>`_ (or `virtualenv for
+Python 2.7 <https://packaging.python.org/en/latest/projects/#virtualenv>`_),
+`pip <https://packaging.python.org/en/latest/projects/#pip>`_, and `setuptools
+<https://packaging.python.org/en/latest/projects/#easy-install>`_.
 
-As an example, for Python 3.3+ on Linux:
+As an example, for Python 3.5+ on Linux:
 
 .. parsed-literal::
 
-  $ pyvenv env33
-  $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python
-  $ env33/bin/easy_install "pyramid==\ |release|\ "
+    $ pyvenv env
+    $ env/bin/pip install pyramid
+    # or for a specific released version
+    $ env/bin/pip install "pyramid==\ |release|\ "
 
 For Windows:
 
 .. parsed-literal::
 
-    # Use your browser to download:
-    #   https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-    c:\\> c:\\Python33\\python -m venv env33
-    c:\\> env33\\Scripts\\python ez_setup.py
-    c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ "
+    c:\\> c:\\Python35\\python -m venv env
+    c:\\> env\\Scripts\\pip install pyramid
+    # or for a specific released version
+    c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ "
 
 Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick
 Tour*. We're just showing Python 3 a little love (Pyramid had production
@@ -44,14 +45,8 @@ support for Python 3 in October 2011).
 
 .. note::
 
-    Why ``easy_install`` and not ``pip``?  Some distributions upon which
-    Pyramid depends have optional C extensions for performance. ``pip`` cannot
-    install some binary Python distributions.  With ``easy_install``, Windows
-    users are able to obtain binary Python distributions, so they get the
-    benefit of the C extensions without needing a C compiler.  Also there can
-    be issues when ``pip`` and ``easy_install`` are used side-by-side in the
-    same environment, so we chose to recommend ``easy_install`` for the sake of
-    reducing the complexity of these instructions.
+    If you use Python 2.6 or 2.7, then you might need to install
+    ``setuptools``. See references below for more information.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
@@ -249,7 +244,7 @@ Chameleon as a :term:`renderer` in our Pyramid application:
 
 .. code-block:: bash
 
-    $ easy_install pyramid_chameleon
+    $ env/bin/pip install pyramid_chameleon
 
 With the package installed, we can include the template bindings into our
 configuration in ``app.py``:
@@ -293,7 +288,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications:
 
 .. code-block:: bash
 
-    $ easy_install pyramid_jinja2
+    $ env/bin/pip install pyramid_jinja2
 
 With the package installed, we can include the template bindings into our
 configuration:
@@ -502,7 +497,7 @@ We next use the normal Python command to set up our package for development:
 .. code-block:: bash
 
     $ cd hello_world
-    $ python ./setup.py develop
+    $ env/bin/pip install -e .
 
 We are moving in the direction of a full-featured Pyramid project, with a
 proper setup for Python standards (packaging) and Pyramid configuration. This
@@ -617,7 +612,7 @@ It was installed when you previously ran:
 
 .. code-block:: bash
 
-    $ python ./setup.py develop
+    $ env/bin/pip install -e .
 
 The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need
 to include its configuration into our web application. The ``pyramid_jinja2``
@@ -670,7 +665,7 @@ following:
           },
 
 We changed ``setup.py`` which means we need to rerun
-``python ./setup.py develop``. We can now run all our tests:
+``env/bin/pip install -e .``. We can now run all our tests:
 
 .. code-block:: bash
 
@@ -746,7 +741,9 @@ These emphasized sections in the configuration file:
 
 Our application, a package named ``hello_world``, is set up as a logger and
 configured to log messages at a ``DEBUG`` or higher level. When you visit
-http://localhost:6543, your console will now show::
+http://localhost:6543, your console will now show:
+
+.. code-block:: text
 
     2016-01-18 13:55:55,040 DEBUG [hello_world.views:10][waitress] Some Message
 
@@ -827,7 +824,7 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold!
 
   $ pcreate --scaffold alchemy sqla_demo
   $ cd sqla_demo
-  $ python setup.py develop
+  $ env/bin/pip install -e .
 
 We now have a working sample SQLAlchemy application with all dependencies
 installed. The sample project provides a console script to initialize a SQLite
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 891305bf5..b263ccbd9 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
@@ -72,6 +72,24 @@ Python 3.5:
    c:\> c:\Python35\Scripts\virtualenv %VENV%
 
 
+Upgrade pip in the virtual environment
+--------------------------------------
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+    $ $VENV/bin/pip install --upgrade pip
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: ps1con
+
+   c:\> %VENV%\Scripts\pip install --upgrade pip
+
+
 Install Pyramid into the virtual Python environment
 ---------------------------------------------------
 
@@ -80,26 +98,27 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/easy_install pyramid
+   $ $VENV/bin/pip install pyramid
 
 On Windows
 ^^^^^^^^^^
 
 .. 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 skip this step.
+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 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:
+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:: bash
 
@@ -168,6 +187,7 @@ On Windows
    and the project into directories that do not contain spaces in their paths.
 
 
+
 .. _installing_project_in_dev_mode:
 
 Installing the project in development mode
@@ -185,7 +205,7 @@ On UNIX
 .. code-block:: bash
 
    $ cd tutorial
-   $ $VENV/bin/python setup.py develop
+   $ $VENV/bin/pip install -e .
 
 On Windows
 ^^^^^^^^^^
@@ -193,7 +213,7 @@ On Windows
 .. code-block:: ps1con
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
+   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::
@@ -215,6 +235,8 @@ On UNIX
 
    $ $VENV/bin/python setup.py test -q
 
+.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046
+
 On Windows
 ^^^^^^^^^^
 
@@ -222,6 +244,8 @@ On Windows
 
    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::
 
    ..
@@ -310,6 +334,13 @@ initialize our database.
    already have a database, you should delete it before running
    ``initialize_tutorial_db`` again.
 
+.. note::
+
+   The ``initialize_tutorial_db`` command is not performing a migration but
+   rather simply creating missing tables and adding some dummy data. If you
+   already have a database, you should delete it before running
+   ``initialize_tutorial_db`` again.
+
 Type the following command, making sure you are still in the ``tutorial``
 directory (the directory with a ``development.ini`` in it):
 
@@ -415,6 +446,13 @@ assumptions:
 
 - You are willing to use :term:`URL dispatch` to map URLs to code.
 
+- You want to use zope.sqlalchemy_, pyramid_tm_ and the transaction_ package
+  to scope sessions to requests.
+
+- You want to use pyramid_jinja2_ to render your templates.
+  Different templating engines can be used but we had to choose one to
+  make the tutorial. See :ref:`available_template_system_bindings` for some
+  options.
 - You want to use zope.sqlalchemy_, pyramid_tm_ and the transaction_ package to
   scope sessions to requests.
 
@@ -440,3 +478,15 @@ assumptions:
 
 .. _transaction:
    http://zodb.readthedocs.org/en/latest/transactions.html
+
+.. _pyramid_jinja2:
+   http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/
+
+.. _pyramid_tm:
+   http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/
+
+.. _zope.sqlalchemy:
+   https://pypi.python.org/pypi/zope.sqlalchemy
+
+.. _transaction:
+   http://zodb.readthedocs.org/en/latest/transactions.html