[MRG+2] DOC framework for keeping API refs for deprecated classes/funcs (scikit-learn#7725)

* DOC framework for keeping API refs for deprecated classes/funcs

* DOC tagging deprecated for 0.20

* suggestion for LDA/QDA deprecation

* simplify deprecation message for GaussianProcess

* simplify deprecation messages

* fixup avoid import QuadraticDiscriminantAnalysis in qda.QDA (and similar for LDA).

* fixup test alias lda.LDA is instance of LinearDiscriminantAnalysis

Author: waterponey

doc/modules/classes.rst

@@ -186,6 +186,7 @@ Splitter Functions
    :template: function.rst
 
    model_selection.train_test_split
+   model_selection.check_cv
 
 Hyper-parameter optimizers
 --------------------------
@@ -201,6 +202,13 @@ Hyper-parameter optimizers
    model_selection.ParameterGrid
    model_selection.ParameterSampler
 
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   model_selection.fit_grid_point
+
 Model validation
 ----------------
 
@@ -315,7 +323,6 @@ Samples generator
    decomposition.PCA
    decomposition.IncrementalPCA
    decomposition.ProjectedGradientNMF
-   decomposition.RandomizedPCA
    decomposition.KernelPCA
    decomposition.FactorAnalysis
    decomposition.FastICA
@@ -560,7 +567,6 @@ From text
 
   gaussian_process.GaussianProcessRegressor
   gaussian_process.GaussianProcessClassifier
-  gaussian_process.GaussianProcess
 
 Kernels:
 
@@ -1349,3 +1355,67 @@ Low-level methods
    utils.estimator_checks.check_estimator
    utils.resample
    utils.shuffle
+
+
+Recently deprecated
+===================
+
+To be removed in 0.19
+---------------------
+
+.. autosummary::
+   :toctree: generated/
+   :template: deprecated_class.rst
+
+   lda.LDA
+   qda.QDA
+
+.. autosummary::
+   :toctree: generated/
+   :template: deprecated_function.rst
+
+   datasets.load_lfw_pairs
+   datasets.load_lfw_people
+
+
+To be removed in 0.20
+---------------------
+
+.. autosummary::
+   :toctree: generated/
+   :template: deprecated_class.rst
+
+   grid_search.ParameterGrid
+   grid_search.ParameterSampler
+   grid_search.GridSearchCV
+   grid_search.RandomizedSearchCV
+   cross_validation.LeaveOneOut
+   cross_validation.LeavePOut
+   cross_validation.KFold
+   cross_validation.LabelKFold
+   cross_validation.LeaveOneLabelOut
+   cross_validation.LeavePLabelOut
+   cross_validation.LabelShuffleSplit
+   cross_validation.StratifiedKFold
+   cross_validation.ShuffleSplit
+   cross_validation.StratifiedShuffleSplit
+   cross_validation.PredefinedSplit
+   decomposition.RandomizedPCA
+   gaussian_process.GaussianProcess
+   mixture.GMM
+   mixture.DPGMM
+   mixture.VBGMM
+
+
+.. autosummary::
+   :toctree: generated/
+   :template: deprecated_function.rst
+
+   grid_search.fit_grid_point
+   learning_curve.learning_curve
+   learning_curve.validation_curve
+   cross_validation.cross_val_predict
+   cross_validation.cross_val_score
+   cross_validation.check_cv
+   cross_validation.permutation_test_score
+   cross_validation.train_test_split

doc/templates/deprecated_class.rst

@@ -0,0 +1,23 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. meta::
+   :robots: noindex
+
+.. warning::
+   **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+   {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/templates/deprecated_class_with_call.rst

@@ -0,0 +1,24 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}===============
+
+.. meta::
+   :robots: noindex
+
+.. warning::
+   **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+   .. automethod:: __call__
+   {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/templates/deprecated_class_without_init.rst

@@ -0,0 +1,19 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. meta::
+   :robots: noindex
+
+.. warning::
+   **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/templates/deprecated_function.rst

@@ -0,0 +1,19 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. meta::
+   :robots: noindex
+
+.. warning::
+   **DEPRECATED**
+
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>

doc/templates/generate_deprecated.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+for f in [^d]*; do (head -n2 < $f; echo '
+.. meta::
+   :robots: noindex
+
+.. warning::
+   **DEPRECATED**
+'; tail -n+3 $f) > deprecated_$f; done

doc/themes/scikit-learn/static/nature.css_t

@@ -603,7 +603,7 @@ div.admonition {
     -moz-border-radius: 4px;
 }
 
-div.warning {
+div.warning, div.deprecated {
     color: #b94a48;
     background-color: #F3E5E5;
     border: 1px solid #eed3d7;

sklearn/cross_validation.py

@@ -109,6 +109,10 @@ def _empty_mask(self):
 class LeaveOneOut(_PartitionIterator):
     """Leave-One-Out cross validation iterator.
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.LeaveOneOut` instead.
+
     Provides train/test indices to split data in train test sets. Each
     sample is used once as a test set (singleton) while the remaining
     samples form the training set.
@@ -171,6 +175,10 @@ def __len__(self):
 class LeavePOut(_PartitionIterator):
     """Leave-P-Out cross validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.LeavePOut` instead.
+
     Provides train/test indices to split data in train test sets. This results
     in testing on all distinct samples of size p, while the remaining n - p
     samples form the training set in each iteration.
@@ -266,6 +274,10 @@ def __init__(self, n, n_folds, shuffle, random_state):
 class KFold(_BaseKFold):
     """K-Folds cross validation iterator.
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.KFold` instead.
+
     Provides train/test indices to split data in train test sets. Split
     dataset into k consecutive folds (without shuffling by default).
 
@@ -357,6 +369,10 @@ def __len__(self):
 class LabelKFold(_BaseKFold):
     """K-fold iterator variant with non-overlapping labels.
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.GroupKFold` instead.
+
     The same label will not appear in two different folds (the number of
     distinct labels has to be at least equal to the number of folds).
 
@@ -459,6 +475,10 @@ def __len__(self):
 class StratifiedKFold(_BaseKFold):
     """Stratified K-Folds cross validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.StratifiedKFold` instead.
+
     Provides train/test indices to split data in train test sets.
 
     This cross-validation object is a variation of KFold that
@@ -581,6 +601,10 @@ def __len__(self):
 class LeaveOneLabelOut(_PartitionIterator):
     """Leave-One-Label_Out cross-validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.LeaveOneGroupOut` instead.
+
     Provides train/test indices to split data according to a third-party
     provided label. This label information can be used to encode arbitrary
     domain specific stratifications of the samples as integers.
@@ -651,6 +675,10 @@ def __len__(self):
 class LeavePLabelOut(_PartitionIterator):
     """Leave-P-Label_Out cross-validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.LeavePGroupsOut` instead.
+
     Provides train/test indices to split data according to a third-party
     provided label. This label information can be used to encode arbitrary
     domain specific stratifications of the samples as integers.
@@ -762,6 +790,10 @@ def _iter_indices(self):
 class ShuffleSplit(BaseShuffleSplit):
     """Random permutation cross-validation iterator.
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.ShuffleSplit` instead.
+
     Yields indices to split data into training and test sets.
 
     Note: contrary to other cross-validation strategies, random splits
@@ -963,6 +995,10 @@ def _approximate_mode(class_counts, n_draws, rng):
 class StratifiedShuffleSplit(BaseShuffleSplit):
     """Stratified ShuffleSplit cross validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.StratifiedShuffleSplit` instead.
+
     Provides train/test indices to split data in train test sets.
 
     This cross-validation object is a merge of StratifiedKFold and
@@ -1085,6 +1121,10 @@ def __len__(self):
 class PredefinedSplit(_PartitionIterator):
     """Predefined split cross validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.PredefinedSplit` instead.
+
     Splits the data into training/test set folds according to a predefined
     scheme. Each sample can be assigned to at most one test set fold, as
     specified by the user through the ``test_fold`` parameter.
@@ -1140,6 +1180,10 @@ def __len__(self):
 class LabelShuffleSplit(ShuffleSplit):
     """Shuffle-Labels-Out cross-validation iterator
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :class:`sklearn.model_selection.GroupShuffleSplit` instead.
+
     Provides randomized train/test indices to split data according to a
     third-party provided label. This label information can be used to encode
     arbitrary domain specific stratifications of the samples as integers.
@@ -1241,6 +1285,10 @@ def cross_val_predict(estimator, X, y=None, cv=None, n_jobs=1,
                       verbose=0, fit_params=None, pre_dispatch='2*n_jobs'):
     """Generate cross-validated estimates for each input data point
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :func:`sklearn.model_selection.cross_val_predict` instead.
+
     Read more in the :ref:`User Guide <cross_validation>`.
 
     Parameters
@@ -1421,6 +1469,10 @@ def cross_val_score(estimator, X, y=None, scoring=None, cv=None, n_jobs=1,
                     verbose=0, fit_params=None, pre_dispatch='2*n_jobs'):
     """Evaluate a score by cross-validation
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :func:`sklearn.model_selection.cross_val_score` instead.
+
     Read more in the :ref:`User Guide <cross_validation>`.
 
     Parameters
@@ -1724,6 +1776,10 @@ def _shuffle(y, labels, random_state):
 def check_cv(cv, X=None, y=None, classifier=False):
     """Input checker utility for building a CV in a user friendly way.
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :func:`sklearn.model_selection.check_cv` instead.
+
     Parameters
     ----------
     cv : int, cross-validation generator or an iterable, optional
@@ -1781,6 +1837,10 @@ def permutation_test_score(estimator, X, y, cv=None,
                            random_state=0, verbose=0, scoring=None):
     """Evaluate the significance of a cross-validated score with permutations
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :func:`sklearn.model_selection.permutation_test_score` instead.
+
     Read more in the :ref:`User Guide <cross_validation>`.
 
     Parameters
@@ -1882,6 +1942,10 @@ def permutation_test_score(estimator, X, y, cv=None,
 def train_test_split(*arrays, **options):
     """Split arrays or matrices into random train and test subsets
 
+    .. deprecated:: 0.18
+        This module will be removed in 0.20.
+        Use :func:`sklearn.model_selection.train_test_split` instead.
+
     Quick utility that wraps input validation and
     ``next(iter(ShuffleSplit(n_samples)))`` and application to input
     data into a single call for splitting (and optionally subsampling)