docs(python): Various docstring improvements to testing.assert_* functions

[henryharbeck]

Fixes a few minor docstring issues:

• Fix see also links in DataFrame.equals and Series.equals
• Catch exceptions in assert_* functions and don't skip the doctests
  • The docstrings had a few errors, and formatting issues in the docs (in the case of assert_frame_equal), so I think this is worthwhile
• Differentiate between DataFrames and LazyFrames in the AssertionError in assert_frame_not_equal as is done in assert_frame_equal

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 79.86%. Comparing base (a5dc30d) to head (9a92367).
Report is 21 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #18494      +/-   ##
==========================================
+ Coverage   79.84%   79.86%   +0.02%     
==========================================
  Files        1501     1501              
  Lines      202032   202033       +1     
  Branches     2868     2868              
==========================================
+ Hits       161309   161354      +45     
+ Misses      40176    40132      -44     
  Partials      547      547              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[MarcoGorelli]

thanks @henryharbeck

nice one on the links, not sure about the docstring changes though

if I do

    Examples
    --------
    >>> from polars.testing import assert_frame_equal
    >>> df1 = pl.DataFrame({"a": [1, 2, 3]})
    >>> df2 = pl.DataFrame({"a": [1, 5, 3]})
    >>> assert_frame_equal(df1, df2)
    Traceback (most recent call last):
    ...
    AssertionError: DataFrames are different (value mismatch for column 'a')
    [left]:  [1, 2, 3]
    [right]: [1, 5, 3]

then the doctest passes without having to skip it, would that work instead of try/except?

[henryharbeck]

Thank you @MarcoGorelli!
Given they were skipped, I wrongly assumed assumed you could not doctest code that raised. Sorry, I should have checked that out. I much prefer your suggestion to the try/except, so have just pushed an update.

Appreciate the constructive review.

[MarcoGorelli]

thanks @henryharbeck ! leaving open a bit in case anyone objects, then will ship it