Add doctests / inline examples in API reference

[Luthaf]

We already have some end-to-end examples/tutorials. These show how to accomplish a high level goal with this library ("how do I create a projection of my dataset using KPCovR").

It would be nice to also have "inline" examples inside the reference documentation, showing how to use each function separately ("how do I call FPS.fit with warm_start=True"). For a good example of how this would look like, see https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html#sklearn.decomposition.PCA.transform.

The standard tool to add such example in Python is called doctests: one write input code as if there was a python prompt (>>>); and the corresponding output. Then, there are tools to run the input code and check that output match. Check out the corresponding module in python standard library: https://docs.python.org/3/library/doctest.html

The first task for this issue would be to make sure doctests are part of the test suite checked on CI

We already have some classes with such examples (https://scikit-cosmo.readthedocs.io/en/latest/preprocessing.html#skcosmo.preprocessing.flexible_scaler.KernelNormalizer), but I think all classes should come with such a small example.

The second task for this issue would be to add doctests/examples to all classes in skcosmo.

[Luthaf]

Looks like we have examples for most of the functions!

[Luthaf]

Actually, I closed this a bit too fast: we have examples for most functions, but not all of them have doctests.

Here is an example of a doctest, actually checking the output of the code: https://github.com/lab-cosmo/scikit-matter/blob/45cff6a81c9136126518bb621101c53ec6e7565a/src/skmatter/decomposition/_pcovr.py#L174-L193

Here is a list of functions/classes without doctests:

• [ ] SparseKernelCenterer
• [x] CUR
• [x] FPS
• [x] PCovCUR
• [x] PCovFPS
• [x] VoronoiFPS
• [x] DirectionalConvexHull
• [ ] RidgeRegression2FoldCV
• [ ] OrthogonalRegression
• [ ] pointwise_global_reconstruction_error
• [ ] global_reconstruction_error
• [ ] pointwise_global_reconstruction_distortion
• [ ] global_reconstruction_distortion
• [ ] pointwise_local_reconstruction_error
• [ ] local_reconstruction_error
• [ ] skmatter.utils._pcovr_utils.pcovr_kernel
• [ ] skmatter.utils._pcovr_utils.pcovr_covariance
• [ ] skmatter.utils._orthogonalizers.Y_feature_orthogonalizer
• [ ] skmatter.utils._orthogonalizers.Y_sample_orthogonalizer

[agoscinski]

PR https://github.com/scikit-learn-contrib/scikit-matter/pull/201 moved examples to doctest for several of them, I ticket the boxes.