Improve documentation UX for sync and async APIs

[sethmlarson]

Some discussions around how we can provide both examples and an API reference for Hip when there are namespaces with very similar but obviously have basically two separate audiences.

A great idea from @njsmith was to do something similar to a lot of projects that support multiple programming languages (Python, Java, Ruby, etc) and have a "Sync / Async" toggle on documentation navigation. Would change all code examples and autodoc refs from ahip to hip, have/exclude async/await etc.

This would be especially useful for the reference as it will be mostly symmetrical thanks to unasync.

Some thoughts and ideas that came up:

• When you're on a sync / async page toggling the slider should bring you to the corresponding page and restore your scroll position on the new page.
  • The toggle can probably be a piece of JavaScript that does URL rewriting as long as the doc URLs are symmetric (/ref/async/... to /ref/sync/...)
  • Could use fragments, scroll %, a combination of both to restore scroll position?
• There will probably be a need for being able to mark sections as "sync-only" and "async-only" for gotchas, tips, limitations, etc
• Should this slider be extended to Sync, Trio, Asyncio, Curio?
  • Some examples will probably want to use specific APIs like trio.run() or trio.open_nursery()
    for showing off how to do multiple concurrent requests.

[pquentin]

What do you think about using something like https://djungelorm.github.io/sphinx-tabs/#code-tabs?

When you choose a different language, all other snippets in the page automatically show that language.

This specific extension does not degrade gracefully: without JS we only see the first tab instead of seeing all of them. I guess that's fixable. But at least that's a solution that already works today.

Should this slider be extended to Sync, Trio, Asyncio, Curio?

I guess ultimately including all frameworks we support is nice because I prefer code snippets that can be run as-is. It shouldn't be too hard as everything should be generated anyway. But it's not mandatory either, just a nice touch.

[sethmlarson]

Maybe the tabbed approach can be used for the asynclib-specific examples and the global Sync / Async can apply to the API ref