Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 286 insertions, 161 deletions

diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index 30fb67441..dbf995595 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -1,269 +1,394 @@
+.. _wiki_installation:
+
 ============
 Installation
 ============
 
-For the most part, the installation process for this tutorial
-duplicates the steps described in :ref:`installing_chapter` and
-:ref:`project_narr`, however it also explains how to install
-additional libraries for tutorial purposes.
+Before you begin
+----------------
+
+This tutorial assumes that you have already followed the steps in
+:ref:`installing_chapter`, except **do not create a virtual environment or
+install Pyramid**.  Thereby you will satisfy the following requirements.
+
+* A Python interpreter is installed on your operating system.
+* You've satisfied the :ref:`requirements-for-installing-packages`.
+
 
-Preparation
-========================
+Create directory to contain the project
+---------------------------------------
 
-Please take the following steps to prepare for the tutorial.  The
-steps to prepare for the tutorial are slightly different depending on
-whether you're using UNIX or Windows.
+We need a workspace for our project files.
 
-Preparation, UNIX
------------------
+On UNIX
+^^^^^^^
 
-#. If you don't already have a Python 2.6 interpreter installed on
-   your system, obtain, install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
+.. code-block:: bash
 
-#. Make sure the Python development headers are installed on your system.  If
-   you've installed Python from source, these will already be installed.  If
-   you're using a system Python, you may have to install a ``python-dev``
-   package (e.g. ``apt-get python-dev``).  The headers are not required for
-   Pyramid itself, just for dependencies of the tutorial.
+    $ mkdir ~/pyramidtut
 
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-    $ /path/to/my/Python-2.6/bin/python ez_setup.py
+   c:\> mkdir pyramidtut
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
 
-   .. code-block:: text
+Create and use a virtual Python environment
+-------------------------------------------
 
-    $ /path/to/my/Python-2.6/bin/easy_install virtualenv
+Next let's create a virtual environment workspace for our project.  We will use
+the ``VENV`` environment variable instead of the absolute path of the virtual
+environment.
 
-#. Use that Python's virtualenv to make a workspace:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-     $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages \
-               pyramidtut
+   $ export VENV=~/pyramidtut
+   $ python3 -m venv $VENV
 
-#. Switch to the ``pyramidtut`` directory:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ cd pyramidtut
+   c:\> set VENV=c:\pyramidtut
 
-#. (Optional) Consider using ``source bin/activate`` to make your
-   shell environment wired to use the virtualenv.
+Each version of Python uses different paths, so you will need to adjust the
+path to the command for your Python version.
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+Python 2.7:
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ bin/easy_install pyramid
+   c:\> c:\Python27\Scripts\virtualenv %VENV%
 
-#. Use ``easy_install`` to install ``docutils``, ``repoze.tm2``,
-   ``repoze.zodbconn``, ``nose`` and ``coverage``:
+Python 3.5:
 
-   .. code-block:: text
+.. code-block:: doscon
 
-     $ bin/easy_install docutils repoze.tm2 repoze.zodbconn \
-               nose coverage
+   c:\> c:\Python35\Scripts\python -m venv %VENV%
 
-Preparation, Windows
---------------------
 
-#. Install, or find `Python 2.6
-   <http://python.org/download/releases/2.6.6/>`_ for your system.
+Upgrade ``pip`` and ``setuptools`` in the virtual environment
+-------------------------------------------------------------
 
-#. Install the latest `setuptools` into the Python you
-   obtained/installed/found in the step above: download `ez_setup.py
-   <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.6 installation using a
-   command prompt:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-    c:\> c:\Python26\python ez_setup.py
+    $ $VENV/bin/pip install --upgrade pip setuptools
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
+On Windows
+^^^^^^^^^^
 
-   .. code-block:: text
+.. code-block:: doscon
 
-    c:\> c:\Python26\Scripts\easy_install virtualenv
+   c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
-#. Use that Python's virtualenv to make a workspace:
 
-   .. code-block:: text
+Install Pyramid into the virtual Python environment
+---------------------------------------------------
 
-     c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut
+On UNIX
+^^^^^^^
 
-#. Switch to the ``pyramidtut`` directory:
+.. code-block:: bash
 
-   .. code-block:: text
+   $ $VENV/bin/pip install pyramid
 
-     c:\> cd pyramidtut
+On Windows
+^^^^^^^^^^
 
-#. (Optional) Consider using ``bin\activate.bat`` to make your shell
-   environment wired to use the virtualenv.
+.. code-block:: doscon
 
-#. Use ``easy_install`` to get :app:`Pyramid` and its direct
-   dependencies installed:
+   c:\> %VENV%\Scripts\pip install pyramid
 
-   .. code-block:: text
+Change directory to your virtual Python environment
+---------------------------------------------------
 
-     c:\pyramidtut> Scripts\easy_install pyramid
+Change directory to the ``pyramidtut`` directory, which is both your workspace
+and your virtual environment.
 
-#. Use ``easy_install`` to install ``docutils``, ``repoze.tm2``,
-   ``repoze.zodbconn``, ``nose`` and ``coverage``:
+On UNIX
+^^^^^^^
 
-   .. code-block:: text
+.. code-block:: bash
 
-     c:\pyramidtut> Scripts\easy_install docutils repoze.tm2 ^
-           repoze.zodbconn nose coverage
+   $ cd pyramidtut
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\> cd pyramidtut
 
 .. _making_a_project:
 
-Making a Project
-================
+Making a project
+----------------
 
-Your next step is to create a project.  :app:`Pyramid` supplies a
-variety of scaffolds to generate sample projects.  For this tutorial,
-we will use the :term:`ZODB` -oriented scaffold named ``pyramid_zodb``.
+Your next step is to create a project.  For this tutorial, we will use
+the :term:`scaffold` named ``zodb``, which generates an application
+that uses :term:`ZODB` and :term:`traversal`.
 
-The below instructions assume your current working directory is the
-"virtualenv" named "pyramidtut".
+: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.
 
-On UNIX:
+By passing ``zodb`` into the ``pcreate`` command, the script creates the files
+needed to use ZODB. By passing in our application name ``tutorial``, the script
+inserts that application name into all the required files.
 
-.. code-block:: text
+The below instructions assume your current working directory is "pyramidtut".
 
-  $ bin/paster create -t pyramid_zodb tutorial
+On UNIX
+^^^^^^^
 
-On Windows:
+.. code-block:: bash
 
-.. code-block:: text
+   $ $VENV/bin/pcreate -s zodb tutorial
 
-   c:\pyramidtut> Scripts\paster create -t pyramid_zodb tutorial
+On Windows
+^^^^^^^^^^
 
-.. note:: If you are using Windows, the ``pyramid_zodb`` Paster scaffold
-   doesn't currently deal gracefully with installation into a location
-   that contains spaces in the path.  If you experience startup
-   problems, try putting both the virtualenv and the project into
-   directories that do not contain spaces in their paths.
+.. code-block:: doscon
 
-Installing the Project in "Development Mode"
-============================================
+   c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial
 
-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:`making_a_project`, and run the
-"setup.py develop" command using virtualenv Python interpreter.
+.. note:: If you are using Windows, the ``zodb`` scaffold may not deal
+   gracefully with installation into a location that contains spaces in the
+   path. If you experience startup problems, try putting both the virtual
+   environment and the project into directories that do not contain spaces in
+   their paths.
 
-On UNIX:
 
-.. code-block:: text
+.. _installing_project_in_dev_mode_zodb:
 
-  $ cd tutorial
-  $ ../bin/python setup.py develop
+Installing the project in development mode
+------------------------------------------
 
-On Windows:
+In order to do development on the project easily, you must "register" the
+project as a development egg in your workspace using the ``pip install -e .``
+command. In order to do so, change directory to the ``tutorial`` directory that
+you created in :ref:`making_a_project`, and run the ``pip install -e .``
+command using the virtual environment Python interpreter.
 
-.. code-block:: text
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ cd tutorial
+   $ $VENV/bin/pip install -e .
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut> cd tutorial
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e .
+
+The console will show ``pip`` checking for packages and installing missing
+packages. Success executing this command will show a line like the following:
+
+.. code-block:: bash
+
+   Successfully installed BTrees-4.2.0 Chameleon-2.24 Mako-1.0.4 \
+   MarkupSafe-0.23 Pygments-2.1.3 ZConfig-3.1.0 ZEO-4.2.0b1 ZODB-4.2.0 \
+   ZODB3-3.11.0 mock-2.0.0 pbr-1.8.1 persistent-4.1.1 pyramid-chameleon-0.3 \
+   pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \
+   pyramid-zodbconn-0.7 six-1.10.0 transaction-1.4.4 tutorial waitress-0.8.10 \
+   zc.lockfile-1.1.0 zdaemon-4.1.0 zodbpickle-0.6.0 zodburi-2.0
+
+
+.. _install-testing-requirements_zodb:
+
+Install testing requirements
+----------------------------
+
+In order to run tests, we need to install the testing requirements. This is
+done through our project's ``setup.py`` file, in the ``tests_require`` and
+``extras_require`` stanzas, and by issuing the command below for your
+operating system.
+
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 22
+   :lines: 22-26
+
+.. literalinclude:: src/installation/setup.py
+   :language: python
+   :linenos:
+   :lineno-start: 45
+   :lines: 45-47
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/pip install -e ".[testing]"
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
 
-  C:\pyramidtut> cd tutorial
-  C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
 
 .. _running_tests:
 
-Running the Tests
-=================
+Run the tests
+-------------
 
-After you've installed the project in development mode, you may run
-the tests for the project.
+After you've installed the project in development mode as well as the testing
+requirements, you may run the tests for the project.
 
-On UNIX:
+On UNIX
+^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
-  $ ../bin/python setup.py test -q
+   $ $VENV/bin/py.test tutorial/tests.py -q
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+
+For a successful test run, you should see output that ends like this:
+
+.. code-block:: bash
+
+   .
+   1 passed in 0.24 seconds
+
+
+Expose test coverage information
+--------------------------------
+
+You can run the ``py.test`` command to see test coverage information. This
+runs the tests in the same way that ``py.test`` does, but provides additional
+"coverage" information, exposing which lines of your project are covered by the
+tests.
+
+We've already installed the ``pytest-cov`` package into our virtual
+environment, so we can run the tests with coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
 
-  c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py
 
-Starting the Application
-========================
+If successful, you will see output something like this:
+
+.. code-block:: bash
+
+   ======================== test session starts ========================
+   platform Python 3.5.1, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+   rootdir: /Users/stevepiercy/projects/pyramidtut/tutorial, inifile:
+   plugins: cov-2.2.1
+   collected 1 items
+
+   tutorial/tests.py .
+   ------------------ coverage: platform Python 3.5.1 ------------------
+   Name                   Stmts   Miss  Cover   Missing
+   ----------------------------------------------------
+   tutorial/__init__.py      12      7    42%   7-8, 14-18
+   tutorial/models.py        10      6    40%   9-14
+   tutorial/tests.py         12      0   100%
+   tutorial/views.py          4      0   100%
+   ----------------------------------------------------
+   TOTAL                     38     13    66%
+
+   ===================== 1 passed in 0.31 seconds ======================
+
+Our package doesn't quite have 100% test coverage.
+
+
+.. _wiki-start-the-application:
+
+Start the application
+---------------------
 
 Start the application.
 
-On UNIX:
+On UNIX
+^^^^^^^
 
-.. code-block:: text
+.. code-block:: bash
 
-  $ ../bin/paster serve development.ini --reload
+   $ $VENV/bin/pserve development.ini --reload
 
-On Windows:
+On Windows
+^^^^^^^^^^
 
-.. code-block:: text
+.. code-block:: doscon
 
-  c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
-Exposing Test Coverage Information
-==================================
+.. note::
 
-You can run the ``nosetests`` command to see test coverage
-information.  This runs the tests in the same way that ``setup.py
-test`` does but provides additional "coverage" information, exposing
-which lines of your project are "covered" (or not covered) by the
-tests.
+   Your OS firewall, if any, may pop up a dialog asking for authorization
+   to allow python to accept incoming network connections.
 
-On UNIX:
+If successful, you will see something like this on your console:
 
 .. code-block:: text
 
-  $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+    Starting subprocess with file monitor
+    Starting server in PID 95736.
+    serving on http://127.0.0.1:6543
 
-On Windows:
+This means the server is ready to accept requests.
 
-.. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
-       --cover-erase --with-coverage
+Visit the application in a browser
+----------------------------------
 
-Looks like the code in the ``pyramid_zodb`` scaffold for ZODB projects is
-missing some test coverage, particularly in the file named
-``models.py``.
+In a browser, visit http://localhost:6543/. You will see the generated
+application's default page.
 
-Visit the Application in a Browser
-==================================
+One thing you'll notice is the "debug toolbar" icon on right hand side of the
+page.  You can read more about the purpose of the icon at
+:ref:`debug_toolbar`.  It allows you to get information about your
+application while you develop.
 
-In a browser, visit `http://localhost:6543/ <http://localhost:6543>`_.
-You will see the generated application's default page.
 
-Decisions the ``pyramid_zodb`` Scaffold Has Made For You
-========================================================
+Decisions the ``zodb`` scaffold has made for you
+------------------------------------------------
 
-Creating a project using the ``pyramid_zodb`` scaffold makes the following
+Creating a project using the ``zodb`` scaffold makes the following
 assumptions:
 
-- you are willing to use :term:`ZODB` as persistent storage
-
-- you are willing to use :term:`traversal` to map URLs to code.
+- You are willing to use :term:`ZODB` as persistent storage.
 
-- you want to use imperative code plus a :term:`scan` to perform
-  configuration.
+- You are willing to use :term:`traversal` to map URLs to code.
 
 .. note::
 
-   :app:`Pyramid` supports any persistent storage mechanism (e.g. a SQL
-   database or filesystem files, etc).  :app:`Pyramid` also supports an
-   additional mechanism to map URLs to code (:term:`URL dispatch`).  However,
-   for the purposes of this tutorial, we'll only be using traversal and ZODB.
-
+   :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL
+   database or filesystem files).  It also supports an additional
+   mechanism to map URLs to code (:term:`URL dispatch`).  However, for the
+   purposes of this tutorial, we'll only be using traversal and ZODB.