diff --git a/docs/wsgi.rst b/docs/wsgi.rst
index cff6bb0cf1..3abb21e5a0 100644
--- a/docs/wsgi.rst
+++ b/docs/wsgi.rst
@@ -30,8 +30,8 @@ To compose your pipeline in Python code:
app = make_wsgi_app({}, '/path/to/zope.conf')
-WSGI tools and helpers for Zope
--------------------------------
+Building a Zope instance with WSGI support
+------------------------------------------
Zope ships with several helper scripts to set up a default WSGI-enabled
environment. The document :doc:`operation` walks you through using
``mkwsgiinstance`` for a default configuration that you can use in conjunction
@@ -68,8 +68,8 @@ starting point for changes. The `Python Logging Cookbook
of topics for advanced configurations.
-WSGI server integrations
-------------------------
+Compatible WSGI servers
+-----------------------
This section describes how to integrate specific WSGI servers into your Zope
instance. These servers were chosen because they either have a `PasteDeploy`
entry point or have one provided by shim software, which means they work with
@@ -210,6 +210,87 @@ section will pull in the correct dependencies:
wsgi = ${buildout:directory}/etc/bjoern.ini
+werkzeug
+~~~~~~~~
+`werkzeug `_ is a WSGI library that
+contains not just a WSGI server, but also a powerful debugger. It can
+easily integrate wth Zope using a shim package called `dataflake.wsgi.werkzeug
+`_. See the `Using this package`
+section for how to integrate `werkzeug` using Zope's own ``runwsgi`` script and
+how to create a suitable WSGI configuration.
+
+If you use ``plone.recipe.zope2instance``, the following section will pull in
+the correct dependencies, after you have created a WSGI configuration file:
+
+.. code-block:: ini
+
+ [zopeinstance]
+ recipe = plone.recipe.zope2instance
+ eggs =
+ dataflake.wsgi.werkzeug
+ zodb-temporary-storage = off
+ user = admin:password
+ http-address = 8080
+ wsgi = ${buildout:directory}/etc/werkzeug.ini
+
+
+Debugging Zope applications under WSGI
+--------------------------------------
+You can debug a WSGI-based Zope application the same way you have debugged
+ZServer-based installations in the past. In addition, you can now take
+advantage of WSGI middleware for debugging as well, or debugging facilities
+built into the chosen WSGI server.
+
+When developing your application or debugging, which is the moment you want to
+use debugging tools, you can start your Zope instance in `debug mode`. This
+will run it in the foreground and won't detach from the console so you get error
+output right in your console window. It will also disable all registered
+exception views including ``standard_error_message`` so that exceptions are not
+masked or hidden.
+
+This is how you run Zope in debug mode using the built-in ``runwsgi`` script:
+
+.. code-block:: console
+
+ $ bin/runwsgi -dv etc/zope.ini
+
+If you built your environment using ``plone.recipe.zope2instance`` this is even
+easier (the example presumes the start script is named ``zopeinstance``):
+
+.. code-block:: console
+
+ bin/zopeinstance fg
+
+If you use ``waitress``, you can make it output exception tracebacks in the
+browser by configuring ``expose_tracebacks``. The keyword works in both
+standard and ``plone.recipe.zope2instance`` configurations:
+
+.. code-block:: ini
+
+ [server:main]
+ use = egg:waitress#main
+ host = 127.0.0.1
+ port = 8080
+ expose_tracebacks = True
+
+ ... or ...
+
+ [server:main]
+ paste.server_factory = plone.recipe.zope2instance:main
+ use = egg:plone.recipe.zope2instance#main
+ listen = 0.0.0.0:8080
+ threads = 2
+ expose_tracebacks = True
+
+``werkzeug`` includes a full-featured debugging tool. See the
+`dataflake.wsgi.werkzeug documentation
+`_
+for how to enable the debugger. Once you're up and running, the `werkzeug
+debugger documentation
+`_
+will show you how to use it.
+
+
WSGI documentation links
------------------------
- the WSGI standard is described in `PEP-3333