Document the lifespan event handler parameter

[emilmelnikov]

#799 added support for the lifespan parameter, but it was not reflected in the documentation.

[graingert]

lifespan now takes an async context manager factory, eg an async generator function decorated with @contextlib(2).asynccontextmanager

[graingert]

sorry I lead you wrong here - the TaskGroup context manager will capture any CancelledError for you

Suggested change

	async with anyio.create_task_group() as app.tg:
	try:
	yield
	finally:
	with anyio.CancelScope(shield=True):
	# release async resources
	async with anyio.create_task_group() as app.tg:
	yield
	# release async resources

[graingert]

I do want to somehow document that yield can now throw CancelledError

[graingert]

sometimes you want to acquire/release resources inside the TaskGroup and sometimes you want to acquire/release them outside the TaskGroup and there's no specific answer as they both have different behaviours with their own pros/cons

[uSpike]

I'm not sure we should have the main documentation for lifespan be setting app.tg. That could be a separate topic, but I think the initial introduction to "make a lifespan" example should be as simple as possible.

@contextlib.asynccontextmanager
async def lifespan(app):
    async with some_async_resource():
        yield

[graingert]

that's fair

[emilmelnikov]

I like the simple lifespan example; we can also add a link to anyio documentation on task groups and cancellation.

[graingert]

Blocks #1233

[graingert]

Thanks! Apologies for dragging this one off topic in my original review