docs(python): improve rendering of API docs type signatures, mark PivotOps as deprecated, misc tidy-ups

[alexander-beedie]

Signatures

Found a proper Sphinx build-event hook (autodoc-process-signature) to take advantage of to try and minimise private classpaths. Annoyingly the event doesn't appear to trigger on every signature, but it does take care of a lot of them. Not obvious why some functions are missed - possibly connected to parsing of @overload, but not confirmed yet.

The newly-registered event handler just applies a simple regex to strip any private paths that appear in the signature; it doesn't look at the rest of the docstring (the mutating function itself, along with registration for the event, can be found in conf.py).

Before: (polars.internals.expr.expr.Expr)

After: (Expr)

Misc

• Added deprecation annotations to PivotOps.
• Reduced polars.datatypes.XYZ to polars.XYZ in sidebar nav.
• Other minor tidy-ups (such as sorting data/lazyframe subsections).
• When creating a new venv (make), don't forget about requirements-docs.txt :)

---

Contributes to #4156.
More to come...

[stinodego]

Really happy with this change and your other recent API reference contributions. These have been a thorn in my eye for so long... 👏

[ritchie46]

That's a huge improvement!

[alexander-beedie]

Hopefully I can extend the approach and get every last one of them; the handful that don't get processed by this event (eg: polars.align_frames) really stand out now ;p