Improve wording and structure of pure ASGI middleware docs

[florimondmanca]

This PR is a follow-up based on @Kludex's comment here: #1656 (review)

I went ahead and reviewed the structure of the "Pure ASGI middleware" section, which now looks like this...

• Pure ASGI middleware
  • Writing pure ASGI middleware
  • Using pure ASGI middleware
  • Type annotations
  • Common patterns
    • Processing certain requests only
    • Sending eager responses
    • Inspecting or modifying the request
    • Inspecting or modifying the response
    • Passing information to endpoints
  • Gotchas
    • ASGI middleware should be stateless

Some other notable changes:

• Add a section with an example of wrapping receive ("Inspecting or modifying the request").
• Expand wording to better highlight that WebSocket middleware is just as possible.
• Add links to ASGI event messages docs when appropriate (http.request, http.response.start, etc). Surely, we know them by heart by now 😄 but we can't assume folks will guess what those contain or where to find that info.
• Use tabs to add the "Don't vs Do" examples for the "Stateless middleware" gotcha, as suggested by @euri10, which highlights using the nonlocal syntax ("Do") vs storing in attributes ("Don't").
• Reword the "storing context in scope" based on discussions over at asgiref -- for now, mention this is purely conventional.
• Add the common pattern of wrapping an app around a try/except/finally block.

(I also tweaked some parts outside of the "Pure ASGI" section, mostly for ensuring consistency; happy to defer to a different PR if that seems out of scope.)

To review, you may view the docs locally, using scripts/docs.

[adriangb]

I read over the markdown version. It looks very nice to me, thank you for working on this! I think ASGI middleware is now one of the most comprehensive and well thought out sections of the docs, go team!

[euri10]

amazing @florimondmanca !

[florimondmanca]

Thanks :-)

[Kludex]

Love the way you write. :)

Added some humble comments 🙏

[Kludex]

I usually pay more attention to things when I see admonitions. 🤔 Just saying... Feel free to close it. 😗

[florimondmanca]

The motivation there was to make add those limitations as a section in the navigation, so it's obvious when searching for the "BaseHTTPMiddleware documentation" that "Okay, I can use this, but there are limitations". On the other hand admonitions require scrolling through the actual content to tell.

[iudeen]

This doc is so detailed and elaborate! Thanks for this one!

[iudeen]

Can we add some details on custom Responder? (If it makes sense, and is relevant)

feel free to close

[florimondmanca]

Blocked by… tomchristie/mkautodoc#33 (Not that keen to do an equivalent of encode/httpx#2313 for every Encode project that will be affected through using mkautodoc)

[Kludex]

Blocked by… tomchristie/mkautodoc#33 (Not that keen to do an equivalent of encode/httpx#2313 for every Encode project that will be affected through using mkautodoc)

There's no hurry for the next release, so I guess it's fine to wait. Did you also ping Tom privately on Gitter about this?

[Kludex]

Thanks @florimondmanca 🙏

[florimondmanca]

Merging since I believe this is ready given the resolution of comments and approvals. Thanks all for reviewing!

[gnat]

Great work @florimondmanca !

Especially the Common Patterns section; I just used it to write my own pure ASGI middleware.

That said, newcomers are undoubtedly still gonna be a bit thrown compared to BaseHTTPMiddleware, but the situation is a lot more manageable with this documentation. We still really should asyncio.shield (or whatever the anyio equivalent is) to fix the BackgroundTask bug.

[JarroVGIT]

I just wanted to say: this is written very clearly, thank you for the work @florimondmanca !