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!

[pquentin]

Thanks! LGTM. Sorry for the wait.

[github-actions]

The backport to 9.2 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-9.2 9.2
# Navigate to the new working tree
cd .worktrees/backport-9.2
# Create a new branch
git switch --create backport-3158-to-9.2
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 214a6279fb24688269c97249d5a95fd395814e6a
# Push it to GitHub
git push --set-upstream origin backport-3158-to-9.2
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.2

Then, create a pull request where the base branch is 9.2 and the compare/head branch is backport-3158-to-9.2.