Document running under WSGI server.

.gitignore

@@ -15,4 +15,4 @@ eggs/
 include/
 lib/
 parts/
-doc/.build/
+doc/_build/

.travis.yml

@@ -6,7 +6,7 @@ python:
 
 notifications:
   email:
-    - hanno@hannosch.eu
+    - tseaver@palladion.com
 
 install:
     - python bootstrap.py

doc/CHANGES.rst

@@ -8,6 +8,9 @@ http://docs.zope.org/zope2/
 2.13.23 (unreleased)
 --------------------
 
+- Document running Zope as a WSGI application.  See
+  https://github.com/zopefoundation/Zope/issues/30
+
 - LP #1465432:  Ensure that WSGIPublisher starts / ends interaction at
   request boundaries (analogous to ZPublisher).  Backport from master.
 

doc/INSTALL.rst → doc/INSTALL-buildout.rst

@@ -1,5 +1,5 @@
-Installing and Zope with ``zc.buildout``
-========================================
+Installing Zope with ``zc.buildout``
+====================================
 
 .. highlight:: bash
 

doc/INSTALL-virtualenv.rst

@@ -0,0 +1,73 @@
+Installing Zope with ``virtualenv``
+===================================
+
+.. highlight:: bash
+
+This document describes how to install Zope into a ``virtualenv``.
+
+
+Create a Virtual Environment
+----------------------------
+
+.. code-block:: sh
+
+   $ /opt/Python-2.7.9/bin/virtualenv z213
+   New python executable in z213/bin/python
+   Installing setuptools, pip, wheel...done.
+   $ cd z213
+
+
+Install the Zope2 2.13.22 Software Packages
+-------------------------------------------
+
+.. code-block:: sh
+
+   $ bin/pip install \
+    --trusted-host download.zope.org \
+    --index http://download.zope.org/Zope2/index/2.13.22/ Zope2
+   Collecting Zope2
+   ...
+   Successfully installed ...
+
+Creating a Zope instance
+------------------------
+
+Once you've installed Zope, you will need to create an "instance
+home". This is a directory that contains configuration and data for a
+Zope server process.  The instance home is created using the
+``mkzopeinstance`` script:
+
+.. code-block:: sh
+
+  $ bin/mkzopeinstance
+
+You can specify the Python interpreter to use for the instance
+explicitly:
+
+.. code-block:: sh
+
+  $ bin/mkzopeinstance --python=bin/python
+
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``.  To see the available
+command-line options, run the script with the ``--help`` option:
+
+.. code-block:: sh
+
+   $ bin/mkzopeinstance --help
+
+Using the ``virtualenv`` as the Zope Instance
+---------------------------------------------
+
+You can choose to use the ``virtualenv`` as your Zope instance:
+
+.. code-block:: sh
+
+   $ bin/mkzopeinstance -d .
+
+In this case, the instance files will be located in the
+subdirectories of the ``virtualenv``:
+
+- ``etc/`` will hold the configuration files.
+- ``log/`` will hold the log files.
+- ``var/`` will hold the database files.

doc/Makefile

@@ -9,7 +9,7 @@ PAPER         =
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
@@ -24,52 +24,52 @@ help:
 	@echo "  linkcheck to check all external links for integrity"
 
 clean:
-	-rm -rf .build/*
+	-rm -rf _build/*
 
 html:
-	mkdir -p .build/html .build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+	mkdir -p _build/html _build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
 	@echo
-	@echo "Build finished. The HTML pages are in .build/html."
+	@echo "Build finished. The HTML pages are in _build/html."
 
 pickle:
-	mkdir -p .build/pickle .build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+	mkdir -p _build/pickle _build/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 web: pickle
 
 json:
-	mkdir -p .build/json .build/doctrees
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json
+	mkdir -p _build/json _build/doctrees
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	mkdir -p .build/htmlhelp .build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+	mkdir -p _build/htmlhelp _build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in .build/htmlhelp."
+	      ".hhp project file in _build/htmlhelp."
 
 latex:
-	mkdir -p .build/latex .build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+	mkdir -p _build/latex _build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
-	@echo "Build finished; the LaTeX files are in .build/latex."
+	@echo "Build finished; the LaTeX files are in _build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
-	mkdir -p .build/changes .build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+	mkdir -p _build/changes _build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
 	@echo
-	@echo "The overview file is in .build/changes."
+	@echo "The overview file is in _build/changes."
 
 linkcheck:
-	mkdir -p .build/linkcheck .build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+	mkdir -p _build/linkcheck _build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in .build/linkcheck/output.txt."
+	      "or in _build/linkcheck/output.txt."

doc/WHATSNEW.rst

@@ -70,6 +70,8 @@ More information can be found in the detailed
 WSGI
 ----
 
+See :doc:`WSGI`.
+
 This Zope release comes with native WSGI support. First pioneered in the
 repoze.zope2 project, this capability finally found its way back into the core
 and obsoletes the externally managed project. With WSGI Zope 2 can natively talk
@@ -79,13 +81,11 @@ factoring out capabilities into WSGI endware. It's expected that this new
 deployment model will over time become the default and the old ZServer
 implementation will be deprecated. There's no concrete timeline for this yet.
 
-NOTE: There's no setup documentation nor streamlined instance creation logic
-for a WSGI setup yet. You are expected to know exactly what you are doing if
-you are trying to use this feature.
+.. note::
 
-Due to the way logic is split out into WSGI middleware, some of the
-`ZPublisher.pubevents` aren't emitted by the WSGI publisher. These are:
-`PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`.
+   Due to the way logic is split out into WSGI middleware, some of the
+   `ZPublisher.pubevents` aren't emitted by the WSGI publisher. These are:
+   `PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`.
 
 
 Zope Toolkit