untangle some docs about using alternate wsgi servers (divide into 2 sections, one about pserve, the other about waitress vs. others)

2 files changed, 56 insertions, 27 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index e4de15bd6..8307c0472 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -983,3 +983,15 @@ Glossary
       :meth:`pyramid.path.AssetResolver.resolve` method.  It supports the
       methods and attributes documented in
       :class:`pyramid.interfaces.IAssetDescriptor`.
+
+   Waitress
+      A :term:`WSGI` server that runs on UNIX and Windows under Python 2.6+
+      and Python 3.2+.  Projects generated via Pyramid scaffolding use
+      Waitress as a WGSI server.  See
+      http://docs.pylonsproject.org/projects/waitress/en/latest/ for detailed
+      information.
+
+   Green Unicorn
+      Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under
+      Python 2.5+ (although at the time of this writing does not support
+      Python 3).  See http://gunicorn.org/ for detailed information.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 896b65249..5696b0b73 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -881,37 +881,54 @@ configuration as would be loaded if you were running your Pyramid application
 via ``pserve``.  This can be a useful debugging tool.  See
 :ref:`interactive_shell` for more details.
 
-.. _alternate_wsgi_server:
+What Is This ``pserve`` Thing
+-----------------------------
 
-Using an Alternate WSGI Server
-------------------------------
-
-The code generated by :app:`Pyramid` scaffolding assumes that you will be
+The code generated by an :app:`Pyramid` scaffold assumes that you will be
 using the ``pserve`` command to start your application while you do
-development.  The default rendering of Pyramid scaffolding uses the
-*waitress* WSGI server, which is a server that is suited for production
-usage.  It's not very fast, or very featureful: its main feature is that it
-works on all platforms and all systems, making it a good choice as a default
-server from the perspective of Pyramid's developers.
+development.  ``pserve`` is a command that reads a :term:`PasteDeploy`
+``.ini`` file (e.g. ``development.ini``) and configures a server to serve a
+Pyramid application based on the data in the file.
 
 ``pserve`` is by no means the only way to start up and serve a :app:`Pyramid`
 application.  As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be
 invoked at all to run a :app:`Pyramid` application.  The use of ``pserve`` to
 run a :app:`Pyramid` application is purely conventional based on the output
-of its scaffold.
-
-Any :term:`WSGI` server is capable of running a :app:`Pyramid` application.
-Some WSGI servers don't require the :term:`PasteDeploy` framework's
-``pserve`` command to do server process management at all.  Each :term:`WSGI`
-server has its own documentation about how it creates a process to run an
-application, and there are many of them, so we cannot provide the details for
-each here.  But the concepts are largely the same, whatever server you happen
-to use.
-
-One popular production alternative to a ``pserve``-invoked server is
-:term:`mod_wsgi`. You can also use :term:`mod_wsgi` to serve your
-:app:`Pyramid` application using the Apache web server rather than any
-"pure-Python" server that is started as a result of ``pserve``.  See
-:ref:`modwsgi_tutorial` for details.  However, it is usually easier to
-*develop* an application using a ``pserve`` -invoked webserver, as
-exception and debugging output will be sent to the console.
+of its scaffolding.  But we strongly recommend using while developing your
+application, because many other convenience introspection commands (such as
+``pviews``, ``prequest``, ``proutes`` and others) are also implemented in
+terms of configuration availaibility of this ``.ini`` file format.  It also
+configures Pyramid logging and provides the ``--reload`` switch for
+convenient restarting of the server when code changes.
+
+.. _alternate_wsgi_server:
+
+Using an Alternate WSGI Server
+------------------------------
+
+Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI
+server.  Waitress is a server that is suited for development and light
+production usage.  It's not the fastest nor the most featureful WSGI server.
+Instead, its main feature is that it works on all platforms that Pyramid
+needs to run on, making it a good choice as a default server from the
+perspective of Pyramid's developers.  
+
+Any WSGI server is capable of running a :app:`Pyramid` application.  But we
+suggest you stick with the default server for development, and that you wait
+to investigate other server options until you're ready to deploy your
+application to production.  Unless for some reason you need to develop on a
+non-local system, investigating alternate server options is usually a
+distraction until you're ready to deploy.  But we recommend developing using
+the default configuration on a local system that you have complete control
+over; it will provide the best development experience.
+
+One popular production alternative to the default Waitress server is
+:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid`
+application using the Apache web server rather than any "pure-Python" server
+like Waitress.  It is fast and featureful.  See :ref:`modwsgi_tutorial` for
+details.
+
+Another good production alternative is :term:`Green Unicorn` (aka
+``gunicorn``).  It's faster than Waitress and slightly easier to configure
+than mod_wsgi, although it depends, in its default configuration, on having a
+buffering HTTP proxy in front of it.