DOC validate docsring using numpydoc conventions (#640)

Author: glemaitre

.travis.yml

@@ -30,17 +30,17 @@ matrix:
   include:
     # This environment tests the using anaconda
     # Ubuntu 14.04 environment
-    - env: DISTRIB="ubuntu" TEST_DOC="true"
+    - env: DISTRIB="ubuntu" TEST_DOC="true" TEST_NUMPYDOC="false"
     # Latest release
     - env: DISTRIB="conda" PYTHON_VERSION="3.7"
            NUMPY_VERSION="*" SCIPY_VERSION="*" SKLEARN_VERSION="master"
-           OPTIONAL_DEPS="keras" TEST_DOC="true"
+           OPTIONAL_DEPS="keras" TEST_DOC="true" TEST_NUMPYDOC="false"
     - env: DISTRIB="conda" PYTHON_VERSION="3.7"
            NUMPY_VERSION="*" SCIPY_VERSION="*" SKLEARN_VERSION="master"
-           OPTIONAL_DEPS="tensorflow" TEST_DOC="true"
+           OPTIONAL_DEPS="tensorflow" TEST_DOC="true" TEST_NUMPYDOC="false"
     - env: DISTRIB="conda" PYTHON_VERSION="3.7"
            NUMPY_VERSION="*" SCIPY_VERSION="*" SKLEARN_VERSION="master"
-           OPTIONAL_DEPS="false" TEST_DOC="false"
+           OPTIONAL_DEPS="false" TEST_DOC="false" TEST_NUMPYDOC="true"
 
 install: source build_tools/travis/install.sh
 script: bash build_tools/travis/test_script.sh

build_tools/travis/install.sh

@@ -52,6 +52,7 @@ if [[ "$DISTRIB" == "conda" ]]; then
 
     conda install --yes pytest pytest-cov
     pip install codecov
+    pip install -U git+https://github.com/numpy/numpydoc.git
 
 elif [[ "$DISTRIB" == "ubuntu" ]]; then
     # At the time of writing numpy 1.9.1 is included in the travis

build_tools/travis/test_script.sh

@@ -28,6 +28,11 @@ run_tests(){
     if [[ "$TEST_DOC" == "true" ]]; then
         make test-doc
     fi
+
+    # Validate numpydoc style
+    if [[ "$TEST_NUMPYDOC" == "true" ]]; then
+        pytest -vsl maint_tools/test_docstring.py
+    fi
 }
 
 if [[ "$SKIP_TESTS" != "true" ]]; then

imblearn/base.py

@@ -32,17 +32,16 @@ def fit(self, X, y):
 
         Parameters
         ----------
-        X : {array-like, sparse matrix}, shape (n_samples, n_features)
+        X : {array-like, sparse matrix} of shape (n_samples, n_features)
             Data array.
 
-        y : array-like, shape (n_samples,)
+        y : array-like of shape (n_samples,)
             Target array.
 
         Returns
         -------
         self : object
             Return the instance itself.
-
         """
         X, y, _ = self._check_X_y(X, y)
         self.sampling_strategy_ = check_sampling_strategy(
@@ -55,21 +54,20 @@ def fit_resample(self, X, y):
 
         Parameters
         ----------
-        X : {array-like, sparse matrix}, shape (n_samples, n_features)
+        X : {array-like, sparse matrix} of shape (n_samples, n_features)
             Matrix containing the data which have to be sampled.
 
-        y : array-like, shape (n_samples,)
+        y : array-like of shape (n_samples,)
             Corresponding label for each sample in X.
 
         Returns
         -------
-        X_resampled : {array-like, sparse matrix}, shape \
-(n_samples_new, n_features)
+        X_resampled : {array-like, sparse matrix} of shape \
+                (n_samples_new, n_features)
             The array containing the resampled data.
 
-        y_resampled : array-like, shape (n_samples_new,)
+        y_resampled : array-like of shape (n_samples_new,)
             The corresponding label of `X_resampled`.
-
         """
         check_classification_targets(y)
         X, y, binarize_y = self._check_X_y(X, y)
@@ -97,20 +95,20 @@ def _fit_resample(self, X, y):
 
         Parameters
         ----------
-        X : {array-like, sparse matrix}, shape (n_samples, n_features)
+        X : {array-like, sparse matrix} of shape (n_samples, n_features)
             Matrix containing the data which have to be sampled.
 
-        y : array-like, shape (n_samples,)
+        y : array-like of shape (n_samples,)
             Corresponding label for each sample in X.
 
         Returns
         -------
-        X_resampled : {ndarray, sparse matrix}, shape \
-(n_samples_new, n_features)
+        X_resampled : {ndarray, sparse matrix} of shape \
+                (n_samples_new, n_features)
             The array containing the resampled data.
 
-        y_resampled : ndarray, shape (n_samples_new,)
-            The corresponding label of `X_resampled`
+        y_resampled : ndarray of shape (n_samples_new,)
+            The corresponding label of `X_resampled`.
 
         """
         pass
@@ -146,26 +144,30 @@ class FunctionSampler(BaseSampler):
 
     Parameters
     ----------
-    func : callable or None,
+    func : callable, default=None
         The callable to use for the transformation. This will be passed the
         same arguments as transform, with args and kwargs forwarded. If func is
         None, then func will be the identity function.
 
-    accept_sparse : bool, optional (default=True)
+    accept_sparse : bool, default=True
         Whether sparse input are supported. By default, sparse inputs are
         supported.
 
-    kw_args : dict, optional (default=None)
+    kw_args : dict, default=None
         The keyword argument expected by ``func``.
 
     validate : bool, default=True
         Whether or not to bypass the validation of ``X`` and ``y``. Turning-off
         validation allows to use the ``FunctionSampler`` with any type of
         data.
 
+    See Also
+    --------
+
+    sklearn.preprocessing.FunctionTransfomer : Stateless transformer.
+
     Notes
     -----
-
     See
     :ref:`sphx_glr_auto_examples_plot_outlier_rejections.py`
 
@@ -204,7 +206,6 @@ class FunctionSampler(BaseSampler):
     >>> print('Resampled dataset shape {}'.format(
     ...     sorted(Counter(y_res).items())))
     Resampled dataset shape [(0, 100), (1, 100)]
-
     """
 
     _sampling_type = "bypass"
@@ -222,21 +223,20 @@ def fit_resample(self, X, y):
 
         Parameters
         ----------
-        X : {array-like, sparse matrix}, shape (n_samples, n_features)
+        X : {array-like, sparse matrix} of shape (n_samples, n_features)
             Matrix containing the data which have to be sampled.
 
-        y : array-like, shape (n_samples,)
+        y : array-like of shape (n_samples,)
             Corresponding label for each sample in X.
 
         Returns
         -------
-        X_resampled : {array-like, sparse matrix}, shape \
-(n_samples_new, n_features)
+        X_resampled : {array-like, sparse matrix} of shape \
+                (n_samples_new, n_features)
             The array containing the resampled data.
 
-        y_resampled : array-like, shape (n_samples_new,)
+        y_resampled : array-like of shape (n_samples_new,)
             The corresponding label of `X_resampled`.
-
         """
         if self.validate:
             check_classification_targets(y)

imblearn/combine/_smote_enn.py

@@ -13,15 +13,17 @@
 from ..under_sampling import EditedNearestNeighbours
 from ..utils import check_target_type
 from ..utils import Substitution
+from ..utils._docstring import _n_jobs_docstring
 from ..utils._docstring import _random_state_docstring
 
 
 @Substitution(
     sampling_strategy=BaseOverSampler._sampling_strategy_docstring,
+    n_jobs=_n_jobs_docstring,
     random_state=_random_state_docstring,
 )
 class SMOTEENN(BaseSampler):
-    """Class to perform over-sampling using SMOTE and cleaning using ENN.
+    """Over-sampling using SMOTE and cleaning using ENN.
 
     Combine over- and under-sampling using SMOTE and Edited Nearest Neighbours.
 
@@ -33,24 +35,23 @@ class SMOTEENN(BaseSampler):
 
     {random_state}
 
-    smote : object, optional (default=SMOTE())
+    smote : object, default=None
         The :class:`imblearn.over_sampling.SMOTE` object to use. If not given,
         a :class:`imblearn.over_sampling.SMOTE` object with default parameters
         will be given.
 
-    enn : object, optional (default=\
-EditedNearestNeighbours(sampling_strategy='all'))
+    enn : object, default=None
         The :class:`imblearn.under_sampling.EditedNearestNeighbours` object
         to use. If not given, a
         :class:`imblearn.under_sampling.EditedNearestNeighbours` object with
         sampling strategy='all' will be given.
 
-    n_jobs : int or None, optional (default=None)
-        Number of CPU cores used during the cross-validation loop.
-        ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context.
-        ``-1`` means using all processors. See
-        `Glossary <https://scikit-learn.org/stable/glossary.html#term-n-jobs>`_
-        for more details.
+    {n_jobs}
+
+    See Also
+    --------
+    SMOTETomek : Over-sample using SMOTE followed by under-sampling removing
+        the Tomek's links.
 
     Notes
     -----
@@ -59,11 +60,6 @@ class SMOTEENN(BaseSampler):
     Supports multi-class resampling. Refer to SMOTE and ENN regarding the
     scheme which used.
 
-    See also
-    --------
-    SMOTETomek : Over-sample using SMOTE followed by under-sampling removing
-        the Tomek's links.
-
     References
     ----------
     .. [1] G. Batista, R. C. Prati, M. C. Monard. "A study of the behavior of
@@ -85,7 +81,6 @@ class SMOTEENN(BaseSampler):
     >>> X_res, y_res = sme.fit_resample(X, y)
     >>> print('Resampled dataset shape %s' % Counter(y_res))
     Resampled dataset shape Counter({{0: 900, 1: 881}})
-
     """
 
     _sampling_type = "over-sampling"

imblearn/combine/_smote_tomek.py

@@ -14,16 +14,17 @@
 from ..under_sampling import TomekLinks
 from ..utils import check_target_type
 from ..utils import Substitution
+from ..utils._docstring import _n_jobs_docstring
 from ..utils._docstring import _random_state_docstring
 
 
 @Substitution(
     sampling_strategy=BaseOverSampler._sampling_strategy_docstring,
+    n_jobs=_n_jobs_docstring,
     random_state=_random_state_docstring,
 )
 class SMOTETomek(BaseSampler):
-    """Class to perform over-sampling using SMOTE and cleaning using
-    Tomek links.
+    """Over-sampling using SMOTE and cleaning using Tomek links.
 
     Combine over- and under-sampling using SMOTE and Tomek links.
 
@@ -35,22 +36,22 @@ class SMOTETomek(BaseSampler):
 
     {random_state}
 
-    smote : object, optional (default=SMOTE())
+    smote : object, default=None
         The :class:`imblearn.over_sampling.SMOTE` object to use. If not given,
         a :class:`imblearn.over_sampling.SMOTE` object with default parameters
         will be given.
 
-    tomek : object, optional (default=TomekLinks(sampling_strategy='all'))
+    tomek : object, default=None
         The :class:`imblearn.under_sampling.TomekLinks` object to use. If not
         given, a :class:`imblearn.under_sampling.TomekLinks` object with
         sampling strategy='all' will be given.
 
-    n_jobs : int or None, optional (default=None)
-        Number of CPU cores used during the cross-validation loop.
-        ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context.
-        ``-1`` means using all processors. See
-        `Glossary <https://scikit-learn.org/stable/glossary.html#term-n-jobs>`_
-        for more details.
+    {n_jobs}
+
+    See Also
+    --------
+    SMOTEENN : Over-sample using SMOTE followed by under-sampling using Edited
+        Nearest Neighbours.
 
     Notes
     -----
@@ -59,11 +60,6 @@ class SMOTETomek(BaseSampler):
     Supports multi-class resampling. Refer to SMOTE and TomekLinks regarding
     the scheme which used.
 
-    See also
-    --------
-    SMOTEENN : Over-sample using SMOTE followed by under-sampling using Edited
-        Nearest Neighbours.
-
     References
     ----------
     .. [1] G. Batista, B. Bazzan, M. Monard, "Balancing Training Data for
@@ -85,7 +81,6 @@ class SMOTETomek(BaseSampler):
     >>> X_res, y_res = smt.fit_resample(X, y)
     >>> print('Resampled dataset shape %s' % Counter(y_res))
     Resampled dataset shape Counter({{0: 900, 1: 900}})
-
     """
 
     _sampling_type = "over-sampling"