Make docstrings pass numpydoc validation

[ogrisel]

See: https://github.com/scikit-learn/scikit-learn/pull/21338

________________________________________________ test_function_docstring[sklearn.utils.fixes.threadpool_info] ________________________________________________

function_name = 'sklearn.utils.fixes.threadpool_info', request = <FixtureRequest for <Function test_function_docstring[sklearn.utils.fixes.threadpool_info]>>

    @pytest.mark.parametrize("function_name", get_all_functions_names())
    def test_function_docstring(function_name, request):
        """Check function docstrings using numpydoc."""
        if function_name in FUNCTION_DOCSTRING_IGNORE_LIST:
            request.applymarker(
                pytest.mark.xfail(run=False, reason="TODO pass numpydoc validation")
            )
    
        res = numpydoc_validation.validate(function_name)
    
        res["errors"] = list(filter_errors(res["errors"], method="function"))
    
        if res["errors"]:
            msg = repr_errors(res, method=f"Tested function: {function_name}")
    
>           raise ValueError(msg)
E           ValueError: 
E           
E           /Users/ogrisel/code/scikit-learn/sklearn/utils/fixes.py
E           
E           Tested function: sklearn.utils.fixes.threadpool_info
E           
E           Return the maximal number of threads for each detected library.
E           
E           Return a list with all the supported libraries that have been found. Each
E           library is represented by a dict with the following information:
E           
E             - "user_api" : user API. Possible values are ['blas', 'openmp'].
E             - "internal_api": internal API. Possible values are ['openmp', 'openblas', 'mkl', 'blis'].
E             - "prefix" : filename prefix of the specific implementation.
E             - "filepath": path to the loaded library.
E             - "version": version of the library (if available).
E             - "num_threads": the current thread limit.
E           
E           In addition, each library may contain internal_api specific entries.
E           
E           # Errors
E           
E            - RT01: No Returns section found

maint_tools/test_docstrings.py:442: ValueError
_______________________________________________ test_function_docstring[sklearn.utils.fixes.threadpool_limits] _______________________________________________

function_name = 'sklearn.utils.fixes.threadpool_limits'
request = <FixtureRequest for <Function test_function_docstring[sklearn.utils.fixes.threadpool_limits]>>

    @pytest.mark.parametrize("function_name", get_all_functions_names())
    def test_function_docstring(function_name, request):
        """Check function docstrings using numpydoc."""
        if function_name in FUNCTION_DOCSTRING_IGNORE_LIST:
            request.applymarker(
                pytest.mark.xfail(run=False, reason="TODO pass numpydoc validation")
            )
    
        res = numpydoc_validation.validate(function_name)
    
        res["errors"] = list(filter_errors(res["errors"], method="function"))
    
        if res["errors"]:
            msg = repr_errors(res, method=f"Tested function: {function_name}")
    
>           raise ValueError(msg)
E           ValueError: 
E           
E           /Users/ogrisel/code/scikit-learn/sklearn/utils/fixes.py
E           
E           Tested function: sklearn.utils.fixes.threadpool_limits
E           
E           Change the maximal number of threads that can be used in thread pools.
E           
E           This object can be used either as a callable (the construction of this object
E           limits the number of threads), as a context manager in a `with` block to
E           automatically restore the original state of the controlled libraries when exiting
E           the block, or as a decorator through its `wrap` method.
E           
E           Set the maximal number of threads that can be used in thread pools used in
E           the supported libraries to `limit`. This function works for libraries that
E           are already loaded in the interpreter and can be changed dynamically.
E           
E           This effect is global and impacts the whole Python process. There is no thread level
E           isolation as these libraries do not offer thread-local APIs to configure the number
E           of threads to use in nested parallel calls.
E           
E           Parameters
E           ----------
E           limits : int, dict or None (default=None)
E               The maximal number of threads that can be used in thread pools
E           
E               - If int, sets the maximum number of threads to `limits` for each
E                 library selected by `user_api`.
E           
E               - If it is a dictionary `{key: max_threads}`, this function sets a
E                 custom maximum number of threads for each `key` which can be either a
E                 `user_api` or a `prefix` for a specific library.
E           
E               - If None, this function does not do anything.
E           
E           user_api : "blas", "openmp" or None (default=None)
E               APIs of libraries to limit. Used only if `limits` is an int.
E           
E               - If "blas", it will only limit BLAS supported libraries (openblas, mkl, blis).
E           
E               - If "openmp", it will only limit OpenMP supported libraries
E                 (libiomp, libgomp, libomp, vcomp). Note that it can affect the number of threads used
E                 by the BLAS libraries if they rely on OpenMP.
E           
E               - If None, this function will apply to all supported libraries.
E           
E           # Errors
E           
E            - RT01: No Returns section found

maint_tools/test_docstrings.py:442: ValueError