Document Klein integration with Twisted services

AUTHORS

@@ -14,3 +14,4 @@ Russel Haering
 Tom Most
 Wilfredo Sánchez Vega
 Evilham
+ac1982

docs/examples/alternativerunning.rst

@@ -5,6 +5,11 @@ Example - Alternatives to app.run
 Sometimes you want to do special things, and the very simple ``Klein.run``
 does not quite fit.
 
+``Klein.run()`` creates a Twisted ``Site`` from ``app.resource()``, starts a listener, sets up logging, and runs the reactor.
+``app.resource()`` itself only returns a Twisted Web resource; it does not listen on a port or start the reactor.
+If a Twisted application already manages your services, use the :doc:`service example <twistd>` to attach Klein to that application.
+For a program that owns the reactor directly, see the manual example below.
+
 
 Example - IPv6, TLS, UNIX sockets, ... (endpoints)
 ==================================================

docs/examples/service.tac

@@ -0,0 +1,18 @@
+from twisted.application import internet, service
+from twisted.web.server import Site
+
+from klein import Klein
+
+app = Klein()
+
+
+@app.route("/")
+def hello(request):
+    return "Hello, world!"
+
+
+site = Site(app.resource())
+site.displayTracebacks = False
+http_service = internet.TCPServer(8080, site, interface="127.0.0.1")
+application = service.Application("klein-example")
+http_service.setServiceParent(application)

docs/examples/twistd.rst

@@ -19,3 +19,30 @@ Here is our "Hello, World!" application again in a form that can be launched by
 To run the above application we can save it as ``helloworld.py`` and use the ``twistd web`` plugin::
 
     PYTHONPATH=. twistd -n web --class=helloworld.resource
+
+
+Adding Klein to an Application
+==============================
+
+To combine Klein with other Twisted services, wrap ``app.resource()`` in a :api:`twisted.web.server.Site <Site>` and pass that factory to :api:`twisted.application.internet.TCPServer <TCPServer>`.
+The resulting service can be attached to your existing ``Application`` or ``MultiService`` with ``setServiceParent``.
+Klein provides the HTTP resource; the parent service manages when the listener starts and stops.
+
+Here is a complete application, saved as ``service.tac``:
+
+.. literalinclude:: service.tac
+   :language: python
+
+Run it in the foreground:
+
+.. code-block:: shell
+
+    twistd -n -y service.tac
+
+Visit ``http://127.0.0.1:8080/`` to see ``Hello, world!``.
+Press Ctrl-C to stop the application and its listener.
+The example binds only to the loopback interface and disables traceback pages.
+
+When adding this to an existing application, use its parent service instead of creating another ``Application``.
+Do not call ``app.run()`` or ``reactor.run()`` in the ``.tac`` file: ``twistd`` runs the reactor and starts and stops the attached services.
+See Twisted's `Application framework guide <https://docs.twisted.org/en/stable/core/howto/application.html>`_ for more about composing services.