docs: Add example for SchemaClass.filter() to docstring

[DeflateAwning]

Motivation

Yesterday, I was bothered when I couldn't find this and had to re-read the quickstart guide.

Today, I still couldn't remember how to do it. There are no hints once you have the bad dataclass instance. Thus, we show the example here.

Changes

Added example to docstring. Copied out of quickstart guide. Having this example in two places makes a lot of sense.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8937816) to head (6849be1).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #188   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           50        50           
  Lines         2918      2918           
=========================================
  Hits          2918      2918           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[delsner]

Thanks, I think it makes sense to have such an example. Would you mind adding it to the Collection class as well? There one receives a dict[str, FailureInfo] in bad.

[DeflateAwning]

Seems reasonable, but I'm not sure what that example should look like.

Can you suggest what the example should look like? Haven't used Collections yet, and the docs don't really have complete enough examples to copy from imo.

[AndreasAlbertQC]

One technical aspect to be aware of: I think our sphinx setup will currently not correctly render markdown in docstrings, because those are handled by sphinx.ext.autodoc, which afaict only supports RST (See also here).