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

rough draft for wiki2, replace setup.py with pip. See #2104.

1 files changed, 110 insertions, 83 deletions

diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index b263ccbd9..a592029cd 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -72,8 +72,8 @@ Python 3.5:
    c:\> c:\Python35\Scripts\virtualenv %VENV%
 
 
-Upgrade pip in the virtual environment
---------------------------------------
+Upgrade ``pip`` in the virtual environment
+------------------------------------------
 
 On UNIX
 ^^^^^^^
@@ -187,16 +187,15 @@ 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
 ------------------------------------------
 
 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``
+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:`sql_making_a_project`, and run the ``setup.py develop``
+you created in :ref:`sql_making_a_project`, and run the ``pip install -e .``
 command using the virtualenv Python interpreter.
 
 On UNIX
@@ -215,106 +214,139 @@ On Windows
    c:\pyramidtut> cd tutorial
    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::
+The console will show ``pip`` checking for packages and installing missing
+packages. Success executing this command will show a line like the following:
 
-   Finished processing dependencies for tutorial==0.0
+.. code-block:: bash
 
-.. _sql_running_tests:
+   Successfully installed Chameleon-2.24 Mako-1.0.4 MarkupSafe-0.23 \
+   Pygments-2.1.3 SQLAlchemy-1.0.12 pyramid-chameleon-0.3 \
+   pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \
+   transaction-1.4.4 tutorial waitress-0.8.10 zope.sqlalchemy-0.7.6
 
-Run the tests
--------------
 
-After you've installed the project in development mode, you may run the tests
-for the project.
+.. _install-testing-requirements:
+
+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 ``testing_extras`` and
+``extras_requires`` 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/python setup.py test -q
-
-.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046
+   $ $VENV/bin/pip install -e ".[testing]"
 
 On Windows
 ^^^^^^^^^^
 
 .. 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
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]"
 
-For a successful test run, you should see output that ends like this::
-
-   ..
-   ----------------------------------------------------------------------
-   Ran 2 tests in 0.053s
 
-   OK
-
-Expose test coverage information
---------------------------------
+.. _sql_running_tests:
 
-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 by the tests.
+Run the tests
+-------------
 
-To get this functionality working, we'll need to install the ``nose`` and
-``coverage`` packages into our ``virtualenv``:
+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
 ^^^^^^^
 
 .. code-block:: bash
 
-   $ $VENV/bin/easy_install nose coverage
+   $ $VENV/bin/py.test tutorial/tests.py -q
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: ps1con
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage
+   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
+
+   ..
+   2 passed in 0.44 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.
 
-Once ``nose`` and ``coverage`` are installed, we can run the tests with
-coverage.
+We've already installed the ``pytest-cov`` package into our ``virtualenv``, so
+we can run the tests with coverage.
 
 On UNIX
 ^^^^^^^
 
 .. code-block:: bash
 
-   $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: ps1con
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
-         --cover-erase --with-coverage
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py
 
-If successful, you will see output something like this::
+If successful, you will see output something like this:
 
-   ..
-   Name                         Stmts   Miss  Cover   Missing
-   ----------------------------------------------------------
-   tutorial.py                      8      6    25%   7-12
-   tutorial/models.py              22      0   100%
-   tutorial/models/meta.py          5      0   100%
-   tutorial/models/mymodel.py       8      0   100%
-   tutorial/scripts.py              0      0   100%
-   tutorial/views.py                0      0   100%
-   tutorial/views/default.py       12      0   100%
-   ----------------------------------------------------------
-   TOTAL                           55      6    89%
-   ----------------------------------------------------------------------
-   Ran 2 tests in 0.579s
-
-   OK
+.. 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 2 items
+
+   tutorial/tests.py ..
+   ------------------ coverage: platform Python 3.5.1 ------------------
+   Name                               Stmts   Miss  Cover   Missing
+   ----------------------------------------------------------------
+   tutorial/__init__.py                   8      6    25%   7-12
+   tutorial/models/__init__.py           22      0   100%
+   tutorial/models/meta.py                5      0   100%
+   tutorial/models/mymodel.py             8      0   100%
+   tutorial/routes.py                     3      3     0%   1-3
+   tutorial/scripts/__init__.py           0      0   100%
+   tutorial/scripts/initializedb.py      26     26     0%   1-45
+   tutorial/tests.py                     39      0   100%
+   tutorial/views/__init__.py             0      0   100%
+   tutorial/views/default.py             12      0   100%
+   tutorial/views/notfound.py             4      4     0%   1-7
+   ----------------------------------------------------------------
+   TOTAL                                127     39    69%
+
+   ===================== 2 passed in 0.57 seconds ======================
 
 Our package doesn't quite have 100% test coverage.
 
@@ -358,15 +390,17 @@ On Windows
 
    c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
 
-The output to your console should be something like this::
+The output to your console should be something like this:
+
+.. code-block:: bash
 
-   2016-02-21 23:57:41,793 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
-   2016-02-21 23:57:41,793 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-02-21 23:57:41,794 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
-   2016-02-21 23:57:41,794 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
-   2016-02-21 23:57:41,796 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models")
-   2016-02-21 23:57:41,796 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-02-21 23:57:41,798 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
+   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 00:53:37,801 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1193][MainThread] ()
+   2016-04-09 00:53:37,802 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models")
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread]
    CREATE TABLE models (
            id INTEGER NOT NULL,
            name TEXT,
@@ -375,15 +409,15 @@ The output to your console should be something like this::
    )
 
 
-   2016-02-21 23:57:41,798 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-02-21 23:57:41,798 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-02-21 23:57:41,799 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
-   2016-02-21 23:57:41,799 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
-   2016-02-21 23:57:41,799 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
-   2016-02-21 23:57:41,801 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
-   2016-02-21 23:57:41,802 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
-   2016-02-21 23:57:41,802 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1)
-   2016-02-21 23:57:41,821 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 00:53:37,803 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,804 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name)
+   2016-04-09 00:53:37,805 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ()
+   2016-04-09 00:53:37,806 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
+   2016-04-09 00:53:37,807 INFO  [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit)
+   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?)
+   2016-04-09 00:53:37,808 INFO  [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1)
+   2016-04-09 00:53:37,809 INFO  [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT
 
 Success!  You should now have a ``tutorial.sqlite`` file in your current
 working directory. This is an SQLite database with a single table defined in it
@@ -446,16 +480,9 @@ 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
+- You want to use zope.sqlalchemy_, pyramid_tm_, and the transaction_ packages
   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.
-
 - You want to use pyramid_jinja2_ to render your templates. Different
   templating engines can be used, but we had to choose one to make this
   tutorial. See :ref:`available_template_system_bindings` for some options.