Restructuring the docs #1421
Description
I think this got quickly mentioned by @tomchristie somewhere around here some time ago, and I pretty much agree, so here's an issue to track it.
Right now the structure of our docs is okay, but there's a lot of room for improvement.
For example:
- We have a quickstart guide (fine), but the rest gets crammed into "Advanced usage", which is just where we pile up docs about various pieces of functionality. Everything being on the same page means it's harder to navigate, we've got less room for some more contextual prose on each feature, etc.
- The quickstart shows a few fundamental features and that's fine, but it also duplicates a bunch of information with what's in "Advanced usage".
- Overall we're missing dedicated, focused and in-depth docs on key areas of HTTPX, such as "Requests and Responses", or "Connection Pooling", or "Transports". Well, we've got bits and pieces here and there, but consolidating all that into dedicated pages, with context, some more prose, examples, etc, could be super helpful for readers.
- "Async Support" is a separate section, but there may be ways to make it more integrated, allowing people to switch from seeing the sync or the async version of each snippet. (In MkDocs-Material this is possible by using snippet tabs.)
I'll be posting a proposed docs structure, just shifting things around so they're nicely grouped into "topic guides" which I think can go a long way in making the docs more helpful as a whole. :)