Revamp proxies documentation

[florimondmanca]

Promted by #927 (comment)

Our current proxies documentation is a bit lacking, and not necessarily nudging users to use the most simple solution whenever possible (i.e. Client(proxies="http://...")), so I dived my head into the world of web proxies and came up with this updated documentation, which outlines:

• Basic usage examples.
• Authentication support.
• Detailed docs about how proxies are routed, and what we support.
• Advanced discussions on forwarding vs tunneling. (Which I think basically boils down to "HTTPX does the right thing for 99% of use cases, and if you know what you're doing here's how you can force things".) I removed the "hide traffic from proxies" example because I don't think we're confident enough to provide any kind of security advice in these docs. Plus I'm not 100% sure that example is a generally advisable thing anyway (eg if you're using your company proxy, then allowing it to intercept the traffic might actually be a corporate security policy requirement).

Rendered preview:

[lovelydinosaur]

👀 Wow, this is fantastic!

Since it ties in here, what are your thoughts on https://github.com/encode/httpx/issues/1105?

I think the docs read even more nicely if we're starting with "all://" progressing to "http://", "https://", and then on to "all://example.com" and so on...

We could already move to using that style in these docs, since it works like that already, we just happen to be special casing the plain "all"/"http"/"https" type cases, but we could gracefully deprecate that. (?)

[lovelydinosaur]

Other thoughts...

• We should remember to update the "See documentation on HTTP_PROXY, HTTPS_PROXY, ALL_PROXY ..." to also include NO_PROXY once that's in there.
• I think we could possibly(?) switch the "Routing algorithm overview" to something a bit more general, that makes it clear that more specific patterns are matched in preference to less specific patterns, without getting into talking about "algorithms" or being quite so specific about implementation details.

[lovelydinosaur]

In any case, going to approve this, since it's fantastic, and we can move on whichever of those items you think is valid (or not).

[lovelydinosaur]

Yas, love it! ✨

[florimondmanca]

Absolutely agree yes, the progression from all:// to http:// to http://domain to http://domain:port would be super sweet! 👍 Still need to take a closer look at #1105 but from afar I like the idea…