fixed docstrings (#2451)

python-package/lightgbm/basic.py

@@ -357,9 +357,9 @@ class _InnerPredictor(object):
     Not exposed to user.
     Used only for prediction, usually used for continued training.
 
-    Note
-    ----
-    Can be converted from Booster, but cannot be converted to Booster.
+    .. note::
+
+        Can be converted from Booster, but cannot be converted to Booster.
     """
 
     def __init__(self, model_file=None, booster_handle=None, pred_parameter=None):
@@ -1939,11 +1939,11 @@ def update(self, train_set=None, fobj=None):
     def __boost(self, grad, hess):
         """Boost Booster for one iteration with customized gradient statistics.
 
-        Note
-        ----
-        For multi-class task, the score is group by class_id first, then group by row_id.
-        If you want to get i-th row score in j-th class, the access way is score[j * num_data + i]
-        and you should group grad and hess in this way as well.
+        .. note::
+
+            For multi-class task, the score is group by class_id first, then group by row_id.
+            If you want to get i-th row score in j-th class, the access way is score[j * num_data + i]
+            and you should group grad and hess in this way as well.
 
         Parameters
         ----------
@@ -2340,13 +2340,13 @@ def predict(self, data, num_iteration=None,
         pred_contrib : bool, optional (default=False)
             Whether to predict feature contributions.
 
-            Note
-            ----
-            If you want to get more explanations for your model's predictions using SHAP values,
-            like SHAP interaction values,
-            you can install the shap package (https://github.com/slundberg/shap).
-            Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
-            column, where the last column is the expected value.
+            .. note::
+
+                If you want to get more explanations for your model's predictions using SHAP values,
+                like SHAP interaction values,
+                you can install the shap package (https://github.com/slundberg/shap).
+                Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
+                column, where the last column is the expected value.
 
         data_has_header : bool, optional (default=False)
             Whether the data has header.
@@ -2526,9 +2526,9 @@ def get_split_value_histogram(self, feature, bins=None, xgboost_style=False):
             If int, interpreted as index.
             If string, interpreted as name.
 
-            Note
-            ----
-            Categorical features are not supported.
+            .. warning::
+
+                Categorical features are not supported.
 
         bins : int, string or None, optional (default=None)
             The maximum number of bins.

python-package/lightgbm/callback.py

@@ -109,9 +109,9 @@ def _callback(env):
 def reset_parameter(**kwargs):
     """Create a callback that resets the parameter after the first iteration.
 
-    Note
-    ----
-    The initial parameter will still take in-effect on first iteration.
+    .. note::
+
+        The initial parameter will still take in-effect on first iteration.
 
     Parameters
     ----------
@@ -154,8 +154,6 @@ def _callback(env):
 def early_stopping(stopping_rounds, first_metric_only=False, verbose=True):
     """Create a callback that activates early stopping.
 
-    Note
-    ----
     Activates early stopping.
     The model will train until the validation score stops improving.
     Validation score needs to improve at least every ``early_stopping_rounds`` round(s)

python-package/lightgbm/engine.py

@@ -101,8 +101,8 @@ def train(params, train_set, num_boost_round=100,
     evals_result: dict or None, optional (default=None)
         This dictionary used to store all evaluation results of all the items in ``valid_sets``.
 
-        Example
-        -------
+        .. rubric:: Example
+
         With a ``valid_sets`` = [valid_set, train_set],
         ``valid_names`` = ['eval', 'train']
         and a ``params`` = {'metric': 'logloss'}
@@ -115,8 +115,8 @@ def train(params, train_set, num_boost_round=100,
         If int, the eval metric on the valid set is printed at every ``verbose_eval`` boosting stage.
         The last boosting stage or the boosting stage found by using ``early_stopping_rounds`` is also printed.
 
-        Example
-        -------
+        .. rubric:: Example
+
         With ``verbose_eval`` = 4 and at least one item in ``valid_sets``,
         an evaluation metric is printed every 4 (instead of 1) boosting stages.
 

python-package/lightgbm/plotting.py

@@ -469,10 +469,10 @@ def create_tree_digraph(booster, tree_index=0, show_info=None, precision=3,
                         old_node_attr=None, old_edge_attr=None, old_body=None, old_strict=False, **kwargs):
     """Create a digraph representation of specified tree.
 
-    Note
-    ----
-    For more information please visit
-    https://graphviz.readthedocs.io/en/stable/api.html#digraph.
+    .. note::
+
+        For more information please visit
+        https://graphviz.readthedocs.io/en/stable/api.html#digraph.
 
     Parameters
     ----------
@@ -545,10 +545,10 @@ def plot_tree(booster, ax=None, tree_index=0, figsize=None,
               show_info=None, precision=3, **kwargs):
     """Plot specified tree.
 
-    Note
-    ----
-    It is preferable to use ``create_tree_digraph()`` because of its lossless quality
-    and returned objects can be also rendered and displayed directly inside a Jupyter notebook.
+    .. note::
+
+        It is preferable to use ``create_tree_digraph()`` because of its lossless quality
+        and returned objects can be also rendered and displayed directly inside a Jupyter notebook.
 
     Parameters
     ----------

python-package/lightgbm/sklearn.py

@@ -40,11 +40,11 @@ def __init__(self, func):
                 hess : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
                     The value of the second order derivative (Hessian) for each sample point.
 
-        Note
-        ----
-        For multi-class task, the y_pred is group by class_id first, then group by row_id.
-        If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i]
-        and you should group grad and hess in this way as well.
+        .. note::
+
+            For multi-class task, the y_pred is group by class_id first, then group by row_id.
+            If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i]
+            and you should group grad and hess in this way as well.
         """
         self.func = func
 
@@ -127,10 +127,10 @@ def __init__(self, func):
                 is_higher_better : bool
                     Is eval result higher better, e.g. AUC is ``is_higher_better``.
 
-        Note
-        ----
-        For multi-class task, the y_pred is group by class_id first, then group by row_id.
-        If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].
+        .. note::
+
+            For multi-class task, the y_pred is group by class_id first, then group by row_id.
+            If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].
         """
         self.func = func
 
@@ -244,9 +244,9 @@ def __init__(self, boosting_type='gbdt', num_leaves=31, max_depth=-1,
             Other parameters for the model.
             Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters.
 
-            Note
-            ----
-            \*\*kwargs is not supported in sklearn, it may cause unexpected issues.
+            .. warning::
+
+                \*\*kwargs is not supported in sklearn, it may cause unexpected issues.
 
         Attributes
         ----------
@@ -421,8 +421,8 @@ def fit(self, X, y,
             If int, the eval metric on the eval set is printed at every ``verbose`` boosting stage.
             The last boosting stage or the boosting stage found by using ``early_stopping_rounds`` is also printed.
 
-            Example
-            -------
+            .. rubric:: Example
+
             With ``verbose`` = 4 and at least one item in ``eval_set``,
             an evaluation metric is printed every 4 (instead of 1) boosting stages.
 
@@ -626,13 +626,13 @@ def predict(self, X, raw_score=False, num_iteration=None,
         pred_contrib : bool, optional (default=False)
             Whether to predict feature contributions.
 
-            Note
-            ----
-            If you want to get more explanations for your model's predictions using SHAP values,
-            like SHAP interaction values,
-            you can install the shap package (https://github.com/slundberg/shap).
-            Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
-            column, where the last column is the expected value.
+            .. note::
+
+                If you want to get more explanations for your model's predictions using SHAP values,
+                like SHAP interaction values,
+                you can install the shap package (https://github.com/slundberg/shap).
+                Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
+                column, where the last column is the expected value.
 
         **kwargs
             Other parameters for the prediction.
@@ -705,12 +705,12 @@ def evals_result_(self):
     def feature_importances_(self):
         """Get feature importances.
 
-        Note
-        ----
-        Feature importance in sklearn interface used to normalize to 1,
-        it's deprecated after 2.0.4 and is the same as Booster.feature_importance() now.
-        ``importance_type`` attribute is passed to the function
-        to configure the type of importance values to be extracted.
+        .. note::
+
+            Feature importance in sklearn interface used to normalize to 1,
+            it's deprecated after 2.0.4 and is the same as Booster.feature_importance() now.
+            ``importance_type`` attribute is passed to the function
+            to configure the type of importance values to be extracted.
         """
         if self._n_features is None:
             raise LGBMNotFittedError('No feature_importances found. Need to call fit beforehand.')
@@ -834,13 +834,13 @@ def predict_proba(self, X, raw_score=False, num_iteration=None,
         pred_contrib : bool, optional (default=False)
             Whether to predict feature contributions.
 
-            Note
-            ----
-            If you want to get more explanations for your model's predictions using SHAP values,
-            like SHAP interaction values,
-            you can install the shap package (https://github.com/slundberg/shap).
-            Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
-            column, where the last column is the expected value.
+            .. note::
+
+                If you want to get more explanations for your model's predictions using SHAP values,
+                like SHAP interaction values,
+                you can install the shap package (https://github.com/slundberg/shap).
+                Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
+                column, where the last column is the expected value.
 
         **kwargs
             Other parameters for the prediction.