docs(python): improve structure of sphinx-generated API docs

[alexander-beedie]

"My fellow Americans Polars enthusiasts, our long national nightmare is over..." ;)
--Gerald Ford

After far, far too many hours today staring at all things Sphinx, I've finally cracked the issue with getting a clean path generated/displayed for the namespace accessors used by the public API (such as arr, dt, str, etc). This reduces the number of excessively long entries in the sidebar navigation down close to zero (dataframe GroupBy and Pivot ops could still do with some cleaning, but I need a break from Sphinx so will tackle that later!)

Also, we have meta information / structure available in the rst files that wasn't being reflected in the navigation, so I broke that out to help make it less overwhelming. Now we have better-contextualised subsections for all Expressions and Series entries. (DataFrame and LazyFrame can follow in another pass).

Minor black magic:

In order for Sphinx (and specifically the sphinx-autosummary-accessors extension) to be able to inspect the methods within the various *NameSpace objects, I needed to make them accessible on the class as well as the instance; this was achieved with the new @accessor decorator (added to polars.utils) which is harmless, but worth mentioning.

Screenshots:

For example...

• Series:

  Adds structure, and renders namespaced methods as you would actually access them -

  

• Expressions:

  As with Series, more structure and clean namespaces -

  

Next:

Would be good to try and cleanup the deep class paths given for many parameters in function/method signatures (such as polars.internals.expr.expr.Expr instead of justExpr... 💭), as well as continue to add structure to the other major pieces of the API (Data/LazyFrames).

Related issues:

Contributes to #4156.
Improves on #4604.
Closes #5341.

[alexander-beedie]

Hmm. Needs a little massaging; will take care of it.

Update: done... will resubmit in a sec.

[ritchie46]

Really nice work! 🙌