DOC: use train_conf_test_split in regression docstrings example, add it to the api doc, and the "Conformity set" doc section (#632)

Author: C-BdB

doc/api.rst

@@ -83,6 +83,15 @@ Metrics
    mapie.metrics.spiegelhalter_statistic
    mapie.metrics.top_label_ece
 
+Utils (from mapie_v1)
+==============================
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   mapie_v1.utils.train_conformalize_test_split
+
 Conformity Scores (Regression)
 ==============================
 

doc/split_cross_conformal.rst

@@ -18,6 +18,7 @@ In all cases, the training/conformalization process can be broken down as follow
 ==============================
 
 - Compute conformity scores ("conformalization") on a conformity set not seen by the model during training.
+  (Use :func:`~mapie_v1.utils.train_conformalize_test_split` to obtain the different sets.)
 
 **MAPIE** then uses the conformity scores to estimate sets associated with the desired coverage on new data with strong theoretical guarantees.
 

mapie_v1/regression.py

@@ -78,14 +78,17 @@ class SplitConformalRegressor:
     Examples
     --------
     >>> from mapie_v1.regression import SplitConformalRegressor
+    >>> from mapie_v1.utils import train_conformalize_test_split
     >>> from sklearn.datasets import make_regression
     >>> from sklearn.model_selection import train_test_split
     >>> from sklearn.linear_model import Ridge
 
     >>> X, y = make_regression(n_samples=500, n_features=2, noise=1.0)
-    >>> X_train, X_conf_test, y_train, y_conf_test = train_test_split(X, y)
-    >>> X_conformalize, X_test, y_conformalize, y_test = train_test_split(
-    ... X_conf_test, y_conf_test
+    >>> (
+    ...     X_train, X_conformalize, X_test,
+    ...     y_train, y_conformalize, y_test
+    ... ) = train_conformalize_test_split(
+    ...     X, y, train_size=0.6, conformalize_size=0.2, test_size=0.2, random_state=1
     ... )
 
     >>> mapie_regressor = SplitConformalRegressor(
@@ -937,14 +940,17 @@ class ConformalizedQuantileRegressor:
     Examples
     --------
     >>> from mapie_v1.regression import ConformalizedQuantileRegressor
+    >>> from mapie_v1.utils import train_conformalize_test_split
     >>> from sklearn.datasets import make_regression
     >>> from sklearn.model_selection import train_test_split
     >>> from sklearn.linear_model import QuantileRegressor
 
     >>> X, y = make_regression(n_samples=500, n_features=2, noise=1.0)
-    >>> X_train, X_conf_test, y_train, y_conf_test = train_test_split(X, y)
-    >>> X_conformalize, X_test, y_conformalize, y_test = train_test_split(
-    ... X_conf_test, y_conf_test
+    >>> (
+    ...     X_train, X_conformalize, X_test,
+    ...     y_train, y_conformalize, y_test
+    ... ) = train_conformalize_test_split(
+    ...     X, y, train_size=0.6, conformalize_size=0.2, test_size=0.2, random_state=1
     ... )
 
     >>> mapie_regressor = ConformalizedQuantileRegressor(