doc: Document API shutdown

Issue sibson#288

docs/library.rst

@@ -4,6 +4,16 @@ vncdotool is built with the Twisted_ framework, as such it best integrates with
 Rewriting your application to use Twisted may not be an option, so vncdotool provides a compatibility layer.
 It uses a separate thread to run the Twisted reactor and communicates with the main program using a thread-safe Queue.
 
+..  warning::
+
+    While the Twisted reactor runs as a *daemon* thread, the reactor itself will start additional *worker threads*, which are *no daemon threads*.
+    Therefore the Reactor must be shut down explicitly by calling :func:`vncdotool.api.shutdown`.
+    Otherwise your application will not terminate as those worker threads remain running in the background.
+
+    This also applied when using the API as a context manager:
+    As the reactor cannot be restarted, it is a design decision to not shut it down as the end of the context.
+    That would prevent the API from being used multiple times in the same process.
+
 To use the synchronous API you can do the following::
 
     from vncdotool import api

vncdotool/api.py

@@ -24,14 +24,15 @@
 V = TypeVar("V")
 TProxy = TypeVar("TProxy", bound="ThreadedVNCClientProxy")
 
-__all__ = ["connect"]
+__all__ = ["shutdown", "connect"]
 
 log = logging.getLogger(__name__)
 
 _THREAD: Optional[threading.Thread] = None
 
 
 def shutdown() -> None:
+    """Shutdown background thread running Twisted reactor."""
     if not reactor.running:
         return
 
@@ -134,7 +135,7 @@ def connect(
     >>> with api.connect('host') as client
     >>>     client.keyPress('c')
 
-    You may then call any regular VNCDoToolClient method on client from your
+    You may then call any regular :py:class:`VNCDoToolClient` method on client from your
     application code.
 
     If you are using a GUI toolkit or other major async library please read