- add more documentation

README.rst

@@ -25,6 +25,12 @@ the `werkzeug WSGI server <https://werkzeug.palletsprojects.com>`_ into an
 environment that uses PasteDeploy-style ``.ini`` files to compose a WSGI
 application.
 
+A second entry point will enable the ``werkzeug`` debugger, so you get nice
+clickable tracebacks with the ability to open a console prompt at any point in
+the stack. The debugger is `explained in the werkzeug documentation 
+<https://werkzeug.palletsprojects.com/debug/>`_ and **should never be running 
+in production**.
+
 It also includes a script to create a basic WSGI configuration file for Zope,
 similar to Zope's own ``mkwsgiinstance``, but specifying ``werkzeug`` instead of
 ``waitress`` as WSGI server.

docs/conf.py

@@ -51,4 +51,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']

docs/usage.rst

@@ -16,19 +16,9 @@ define a ``werkzeug`` server:
 If you leave out the ``host`` specification, ``werkzeug``  will listen on all
 IPv4 interfaces (`0.0.0.0`). The default port, if none is given, is 8080.
 
-``werkzeug`` supports a wide range of configuration options that you can pass as
-part of your WSGI configuration. Here's an example showing all options:
-
-.. code-block:: ini
-
-   [server:main]
-   use = egg:dataflake.wsgi.werkzeug#main
-   hostname = 127.0.0.1
-   port = 8080
-   use_debugger = true
-
-The possible options are listed in the `werkzeug documentation 
-<https://werkzeug.palletsprojects.com/serving/>`_.
+``werkzeug`` supports a wide range of configuration options that you can pass
+as part of your WSGI configuration. They are listed in the
+`werkzeug documentation <https://werkzeug.palletsprojects.com/serving/>`_.
 
 
 Creating a basic WSGI configuration for Zope
@@ -60,3 +50,30 @@ default, ``waitress``.
    Username: admin
    Password: (enter password)
    Verify password: (re-enter password)
+
+
+Using the werkzeug debugger
+---------------------------
+This package has a second entry point to enable the `werkzeug debugger 
+<https://werkzeug.palletsprojects.com/debug/>`_.
+
+.. warning::
+
+   Do not enable the werkzeug debugger in production! Any site visitor
+   may execute Python code on your server using the debugger console!
+
+.. code-block:: ini
+
+   [server:main]
+   use = egg:dataflake.wsgi.werkzeug#debugger
+   host = 127.0.0.1
+   port = 8080
+
+In the ``[server]`` section, you can combine the `werkzeug server options 
+<https://werkzeug.palletsprojects.com/serving/>`_ and the `werkzeug debugger
+options <https://werkzeug.palletsprojects.com/debug/>`_
+
+The debugger will present you with a nice exception traceback display in the
+browser and the ability to open a console prompt at any point in the traceback
+call stack. This is great for developers, but **dangerous if exposed to the
+wider Internet**, so never leave this enabled on a production site.