It would be useful to enforce docstrings style with numpydoc. Currently only a small fraction of docstring pass that validation.

To improve docstring see steps below,

0. Install scikit-learn from sources (see contribution guide).

1. install numpydoc master with,

   pip install https://github.com/numpy/numpydoc/archive/master.zip
   

2. Run the docstring validation on all docstrings,

   pytest maint_tools/test_docstrings.py -v
   

   and choose an estimator with an XFAIL status (meaning that it is a known failure). Write down all of its methods.

3. Run,

   python maint_tools/test_docstrings.py import_path
   

   to see the list of validation errors for a particular method, where import_path can be for instance sklearn.linear_model.LogisticRegression (for the main estimator docstring) or sklearn.linear_model.LogisticRegression.fit (for the docstring of the fit method).

4. Fix the docstring until validation passes. Repeat on all public methods of the chosen estimator.

5. Add the estimator to the whitelist in maint_tools/test_docstrings.py here. Note that this list accepts regular expressions, so LogisticRegression will match all methods of that estimator, and also potentially other estimators e.g. LogisticRegressionCV. For instance one can use LogisticRegression$ to only match the main estimator docstring. When running from step 2, checks for the modified estimators should then pass.

Please write in a comment of this issue, the estimator you are planning to work on. Note that some methods are shared between estimators and are located in other files e.g. estimator.set_params.