Improve documentation

This patch:

* exposes eventlet.greenthread.kill function so Sphinx generates
  its documentation and fixes broken links to :func:`kill`
* adds warning about wsgi.server waiting for active connections to
  finish before returning

doc/modules/websocket.rst

@@ -18,6 +18,11 @@ To create a websocket server, simply decorate a handler method with
     
     wsgi.server(eventlet.listen(('', 8090)), hello_world)
 
+.. note::
+
+    Please see graceful termination warning in :func:`~eventlet.wsgi.server`
+    documentation
+
 
 You can find a slightly more elaborate version of this code in the file
 ``examples/websocket.py``.

eventlet/greenthread.py

@@ -9,6 +9,7 @@ from eventlet.support import greenlets as greenlet, six
 import warnings
 
 __all__ = ['getcurrent', 'sleep', 'spawn', 'spawn_n',
+           'kill',
            'spawn_after', 'spawn_after_local', 'GreenThread']
 
 getcurrent = greenlet.getcurrent

eventlet/wsgi.py

@@ -710,6 +710,19 @@ def server(sock, site,
     closed after server exits, but the underlying file descriptor will
     remain open, so if you have a dup() of *sock*, it will remain usable.
 
+    .. warning::
+
+        At the moment :func:`server` will always wait for active connections to finish before
+        exiting, even if there's an exception raised inside it
+        (*all* exceptions are handled the same way, including :class:`greenlet.GreenletExit`
+        and those inheriting from `BaseException`).
+
+        While this may not be an issue normally, when it comes to long running HTTP connections
+        (like :mod:`eventlet.websocket`) it will become problematic and calling
+        :meth:`~eventlet.greenthread.GreenThread.wait` on a thread that runs the server may hang,
+        even after using :meth:`~eventlet.greenthread.GreenThread.kill`, as long
+        as there are active connections.
+
     :param sock: Server socket, must be already bound to a port and listening.
     :param site: WSGI application function.
     :param log: File-like object that logs should be written to.