Expand the overview section of the docs

[miguelgrinberg]

No description provided.

[github-actions]

🔍 Preview links for changed docs

• docs/reference/index.md

[miguelgrinberg]

@marciw @pquentin Looking for early feedback on this reordering and expansion of the content in the overview page of the docs. I want to make it more clear that there are a number of somewhat independent things all included in this package, so I'm enumerating the four big components, each with links to its high level and reference docs. Let me know what you think, or if you have suggestions to improve this. Thanks!

[pquentin]

This brings a lot of clarity, thank you!

I'd still like to see a code example above the fold, maybe not as a REPL session. I've seen user interviews where users in a hurry don't read anything, but copy/paste the first text snippet they see and try to adapt it to their needs.

[miguelgrinberg]

@pquentin I agree with having a short example above this overview. But the example that we currently feature is not great, first because it shows a console use, which is not what most people would want, and second because it focuses on this obscure fact about serialisation of datetime objects, which has no place at this high-level. I have now replaced the example with a regular search call generated by the request converter, and moved it to the top of the page.

EDIT: now made this example tabbed, with sync and async versions!