Add minimal examples to API documentation

[nevencaplar]

Closes #1240.

[dougbrn]

Nice, I have one larger structural comment, which is that these examples will try to be run by doctest I believe, so anything that produces output will need output alongside the input. That may even result in failed tests, though we wouldn't know for sure until the CI decides to actually do something (not sure what's going on there).

It's also good for these to have output for usefulness, check out map_rows for an example of that: https://docs.lsdb.io/en/latest/reference/api/lsdb.catalog.Catalog.map_rows.html

Generally, running these code blocks on command line will get you a copy-pastable output to put in the docstring.

I'm not sure what the best practice would be for the examples that generate plots...

[github-actions]

Before [e1de1de]	After [a9f12d4]	Ratio	Benchmark (Parameter)
6.89±0.03s	6.95±0.05s	1.01	benchmarks.time_create_large_catalog
1.04±0.01s	1.05±0.02s	1.01	benchmarks.time_create_midsize_catalog
27.7±0.2ms	27.7±0.4ms	1	benchmarks.time_box_filter_on_partition
19.5±0s	19.5±0.02s	1	benchmarks.time_save_big_catalog
8.19±0.02s	8.07±0.01s	0.99	benchmarks.time_lazy_crossmatch_many_columns_all_suffixes
8.19±0.09s	8.03±0.04s	0.98	benchmarks.time_lazy_crossmatch_many_columns_overlapping_suffixes
3.78±0.03s	3.70±0.02s	0.98	benchmarks.time_open_many_columns_all
370±10ms	362±3ms	0.98	benchmarks.time_open_many_columns_default
165±4ms	161±1ms	0.98	benchmarks.time_open_many_columns_list
105±2ms	100±2ms	0.96	benchmarks.time_kdtree_crossmatch

Click here to view all benchmarks.

[nevencaplar]

I did not add output for plotting function or for write_catalog (for write catalog I even have dummy output PATH in the example, i.e., the code cant work automatically the way it is written). Not sure what to do there?

I am also a bit worried about formatting. Is that a problem? My examples look like

                            ra        dec    id
   _healpix_29                                   
  118362963675428450  52.696686  39.675892  8154

while your example in map_rows looks like(difference is _healpix_29 is is in the same row as other columns, index is in front):

      _healpix_29  plus_one  minus_one
 0  1372475556631677955      21.1       20.9

[dougbrn]

@nevencaplar the formatting does matter for the CI, you can lean on the actual failed test results on this PR to see what it expects:

Differences (unified diff with -expected +actual):
    @@ -1,3 +1,3 @@
    -                        ra        dec    id
    +                           ra        dec    id
     _healpix_29                                   
     118362963675428450  52.696686  39.675892  8154

In cases where the code is actually non-operable, at least for CI, I think it's okay to let CI skip it, by adding # doctest: +SKIP as a comment to the output producing line(s)

[dougbrn]

Additionally, with LSDB's current setup pre-commit and doctest disagree on formatting, you will probably want to add # doctest: +NORMALIZE_WHITESPACE to any lines executing code that produce a dataframe to make both of them happy. See an example in from_astropy: https://github.com/astronomy-commons/lsdb/blob/main/src/lsdb/loaders/dataframe/from_astropy.py#L94

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.66%. Comparing base (fbb3fea) to head (acb6232).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1243   +/-   ##
=======================================
  Coverage   96.66%   96.66%           
=======================================
  Files          46       46           
  Lines        2877     2877           
=======================================
  Hits         2781     2781           
  Misses         96       96           

☔ 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.

[nevencaplar]

I believe that all tests are passing, through combination of SKIP , NORMALIZE_WHITESPACE, and reduction of width of output pandas dataframes.

[dougbrn]

Looks great, thank you!