- add section for werkzeug and for debugging Zope applications

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 <https://palletsprojects.com/p/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 
+<https://dataflakewsgiwerkzeug.readthedocs.io/>`_. 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
+<https://dataflakewsgiwerkzeug.readthedocs.io/en/latest/usage.html#using-the-werkzeug-debugger>`_
+for how to enable the debugger. Once you're up and running, the `werkzeug
+debugger documentation
+<https://werkzeug.palletsprojects.com/en/0.15.x/debug/#using-the-debugger>`_
+will show you how to use it.
+
+
 WSGI documentation links
 ------------------------
 - the WSGI standard is described in `PEP-3333