[DOCS] Clarify upgrades and edit generally

[marciw]

👁️ Preview docs/reference/index.md

Summary of changes

• Revised the "Major version upgrades" section in response to https://github.com/elastic/docs-content-internal/issues/421
• Clarified forward compatibility
• Added phrasing and table from .NET docs + made the table more accessible
• Added links to related docs
• Did a general edit for clarity, concision, Elastic style

❗ Notes for reviewers

• I'll apply similar changes to the other client docs. This one will serve as the template for updating the others.
• I tried to align this with both the .NET docs and https://github.com/elastic/devtools-team/pull/936/ (will iterate more when moving the latter to docs-content)

TODO

• Compare to .NET changes; go with the best of both worlds
• Tweak section heading?
• Clarify "outages" (whether clients need hot-swapping during major upgrades) per Upgrade from 7.17 guide docs-content#3398 (comment) <-- will do this in a follow-up issue; going to merge this in its current state as a "phase 1" edit

[github-actions]

🔍 Preview links for changed docs

• docs/reference/index.md

[Copilot]

Pull Request Overview

This PR updates the Python client documentation to improve clarity, structure, and accuracy. The changes modernize the content with better explanations of compatibility, feature descriptions, and client usage.

• Added navigation metadata and improved page title
• Updated compatibility section with a clearer table and explanations
• Reorganized content flow with better placement of examples and tips

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[miguelgrinberg]

@marciw The lint failure is unrelated, I'll fix that separately.

[github-actions]

The backport to 9.0 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.0 9.0
# Navigate to the new working tree
cd .worktrees/backport-9.0
# Create a new branch
git switch --create backport-3138-to-9.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 06f25a0f370c21e511b75e02a87d3e7056e2a00e
# Push it to GitHub
git push --set-upstream origin backport-3138-to-9.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-9.0

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