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

1 files changed, 33 insertions, 37 deletions

diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index 6e3e4ce37..3cc182d13 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -1,18 +1,17 @@
 .. _modwsgi_tutorial:
 
 Running a :app:`Pyramid` Application under ``mod_wsgi``
-==========================================================
+=======================================================
 
 :term:`mod_wsgi` is an Apache module developed by Graham Dumpleton.
 It allows :term:`WSGI` programs to be served using the Apache web
 server.
 
-This guide will outline broad steps that can be used to get a
-:app:`Pyramid` application running under Apache via ``mod_wsgi``.
-This particular tutorial was developed under Apple's Mac OS X platform
-(Snow Leopard, on a 32-bit Mac), but the instructions should be
-largely the same for all systems, delta specific path information for
-commands and files.
+This guide will outline broad steps that can be used to get a :app:`Pyramid`
+application running under Apache via ``mod_wsgi``.  This particular tutorial
+was developed under Apple's Mac OS X platform (Snow Leopard, on a 32-bit
+Mac), but the instructions should be largely the same for all systems, delta
+specific path information for commands and files.
 
 .. note:: Unfortunately these instructions almost certainly won't work for
    deploying a :app:`Pyramid` application on a Windows system using
@@ -25,21 +24,15 @@ commands and files.
     system.  If you do not, install Apache 2.X for your platform in
     whatever manner makes sense.
 
+#.  It is also assumed that you have satisfied the
+    :ref:`requirements-for-installing-packages`.
+
 #.  Once you have Apache installed, install ``mod_wsgi``.  Use the
     (excellent) `installation instructions
     <http://code.google.com/p/modwsgi/wiki/InstallationInstructions>`_
     for your platform into your system's Apache installation.
 
-#.  Install :term:`virtualenv` into the Python which mod_wsgi will
-    run using the ``easy_install`` program.
-
-    .. code-block:: text
-
-       $ sudo /usr/bin/easy_install-2.6 virtualenv
-
-    This command may need to be performed as the root user.
-
-#.  Create a :term:`virtualenv` which we'll use to install our
+#.  Create a :term:`virtual environment` which we'll use to install our
     application.
 
     .. code-block:: text
@@ -47,14 +40,14 @@ commands and files.
        $ cd ~
        $ mkdir modwsgi
        $ cd modwsgi
-       $ /usr/local/bin/virtualenv --no-site-packages env
+       $ python3 -m venv env
 
-#.  Install :app:`Pyramid` into the newly created virtualenv:
+#.  Install :app:`Pyramid` into the newly created virtual environment:
 
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/easy_install pyramid
+       $ $VENV/bin/pip install pyramid
     
 #.  Create and install your :app:`Pyramid` application.  For the purposes of
     this tutorial, we'll just be using the ``pyramid_starter`` application as
@@ -64,20 +57,21 @@ commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/paster create -t pyramid_starter myapp
+       $ $VENV/bin/pcreate -s starter myapp
        $ cd myapp
-       $ ../bin/python setup.py install
+       $ $VENV/bin/pip install -e .
 
-#.  Within the virtualenv directory (``~/modwsgi/env``), create a
+#.  Within the virtual environment directory (``~/modwsgi/env``), create a
     script named ``pyramid.wsgi``.  Give it these contents:
 
     .. code-block:: python
 
-       from pyramid.paster import get_app
-       application = get_app(
-         '/Users/chrism/modwsgi/env/myapp/production.ini', 'main')
+       from pyramid.paster import get_app, setup_logging
+       ini_path = '/Users/chrism/modwsgi/env/myapp/production.ini'
+       setup_logging(ini_path)
+       application = get_app(ini_path, 'main')
 
-    The first argument to ``get_app`` is the project Paste configuration file
+    The first argument to ``get_app`` is the project configuration file
     name.  It's best to use the ``production.ini`` file provided by your
     scaffold, as it contains settings appropriate for
     production.  The second is the name of the section within the .ini file
@@ -85,12 +79,15 @@ commands and files.
     ``application`` is important: mod_wsgi requires finding such an
     assignment when it opens the file.
 
-#.  Make the ``pyramid.wsgi`` script executable.
+    The call to ``setup_logging`` initializes the standard library's
+    `logging` module to allow logging within your application.
+    See :ref:`logging_config`.
 
-    .. code-block:: text
-
-       $ cd ~/modwsgi/env
-       $ chmod 755 pyramid.wsgi
+    There is no need to make the ``pyramid.wsgi`` script executable.
+    However, you'll need to make sure that *two* users have access to change
+    into the ``~/modwsgi/env`` directory: your current user (mine is
+    ``chrism`` and the user that Apache will run as often named ``apache`` or
+    ``httpd``).  Make sure both of these users can "cd" into that directory.
 
 #.  Edit your Apache configuration and add some stuff.  I happened to
     create a file named ``/etc/apache2/other/modwsgi.conf`` on my own
@@ -99,12 +96,12 @@ commands and files.
     .. code-block:: apache
 
        # Use only 1 Python sub-interpreter.  Multiple sub-interpreters
-       # play badly with C extensions.
+       # play badly with C extensions.  See
+       # http://stackoverflow.com/a/10558360/209039
        WSGIApplicationGroup %{GLOBAL}
        WSGIPassAuthorization On
-       WSGIDaemonProcess pyramid user=chrism group=staff processes=1 \
-          threads=4 \
-          python-path=/Users/chrism/modwsgi/env/lib/python2.6/site-packages
+       WSGIDaemonProcess pyramid user=chrism group=staff threads=4 \
+          python-path=/Users/chrism/modwsgi/env/lib/python2.7/site-packages
        WSGIScriptAlias /myapp /Users/chrism/modwsgi/env/pyramid.wsgi
 
        <Directory /Users/chrism/modwsgi/env>
@@ -128,4 +125,3 @@ serve up a :app:`Pyramid` application.  See the `mod_wsgi
 configuration documentation
 <http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines>`_ for
 more in-depth configuration information.
-