Document the lifespan event handler parameter (#1110)

Co-authored-by: Thomas Grainger <tagrain@gmail.com>

diff --git a/docs/events.md b/docs/events.md
index 4f2bce558b3c70360f38433e4fbe6444a700b2c7..c7ed49e9dc28f4d40439edcea77fba747af2a25b 100644 (file)
--- a/docs/events.md
+++ b/docs/events.md
@@ -37,6 +37,31 @@ registered startup handlers have completed.
 The shutdown handlers will run once all connections have been closed, and
 any in-process background tasks have completed.
 
+A single lifespan asynccontextmanager handler can be used instead of
+separate startup and shutdown handlers:
+
+```python
+import contextlib
+import anyio
+from starlette.applications import Starlette
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app):
+    async with some_async_resource():
+        yield
+
+
+routes = [
+    ...
+]
+
+app = Starlette(routes=routes, lifespan=lifespan)
+```
+
+Consider using [`anyio.create_task_group()`](https://anyio.readthedocs.io/en/stable/tasks.html)
+for managing asynchronious tasks.
+
 ## Running event handlers in tests
 
 You might want to explicitly call into your event handlers in any test setup