Document graceful server shutdown

docs/faq/server.rst

@@ -311,6 +311,25 @@ Here's how to adapt the example just above:
 
 The server will exit after all clients disconnect.
 
+With the :mod:`threading` implementation, call ``Server.shutdown`` with
+``close_connections=False`` instead::
+
+    from websockets.sync.server import serve
+    import threading
+
+    server = serve(handler, "localhost", 8765)
+    server_thread = threading.Thread(target=server.serve_forever)
+    server_thread.start()
+    try:
+        # Run the application until it's time to stop.
+        ...
+    finally:
+        server.shutdown(close_connections=False)
+        server_thread.join()
+
+The server will return from ``Server.shutdown`` after all clients
+disconnect.
+
 How do I implement a health check?
 ----------------------------------
 

docs/project/changelog.rst

@@ -43,6 +43,9 @@ Improvements
 
 * :func:`~asyncio.client.connect` now closes connections with close code 1011
   (internal error) when exiting the context manager with an exception.
+* The FAQ documents how to stop asyncio and threading servers while keeping
+  existing connections open. See `issue #1756
+  <https://github.com/python-websockets/websockets/issues/1756>`_.
 
 .. _17.1: