[docs] [dask] Add return information to Dask fit() docs (fixes #4402)

[jameslamb]

Fixes #4402, adding Returns blocks to the documentation for fit() method on estimators in lightgbm.dask.

How I tested this

cd docs
make clean html
open _build/html/index.html

Looks like the docs are rendering correctly.

I also clicked through the links next to Return type and confirmed that they link back to the constructor docs for the relevant class.

[jmoralez]

Looking at the current scikit-learn estimators (Classifier, Regressor) I see that the return type is object, however this seems better (specifying the return type as the estimator itself and linking to the constructor), should we open a new issue to change that?

Also looking at scikit-learn docs they specify that the fit method returns the fitted estimator. So maybe we could change it to something like:

    Returns
    -------
    self : lightgbm.DaskLGBMClassifier
        Fitted estimator.

WDYT @jameslamb?

[StrikerRUS]

@jameslamb

I also clicked through the links next to Return type and confirmed that they link back to the constructor docs for the relevant class.

Can this behavior be preserved without lightgbm. prefix in the return type?
I hope it can, given the following example

LightGBM/python-package/lightgbm/engine.py

Lines 163 to 166 in 1cc84b3

	Returns
	-------
	booster : Booster
	The trained Booster model.

https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.train.html#lightgbm.train

I think it will be good to match naming schema that is used around all other docstrings. E.g.,

LightGBM/python-package/lightgbm/dask.py

Line 451 in 1cc84b3

Default: 'l2' for DaskLGBMRegressor, 'binary(multi)_logloss' for DaskLGBMClassifier, 'ndcg' for DaskLGBMRanker.

[StrikerRUS]

Ah, just looked through the codebase more carefully and it seems lightgbm.dask is already using lightgbm. prefix everywhere in docstrings for referring to its classes. Please forget my previous comment #4716 (comment) then.

[jameslamb]

Thanks for the reviews! I just updated this to latest master. If it passes, I'll merge this.

@jmoralez I agree with your suggestion to update the same information from the sklearn docstrings. I'll propose those changes in a separate PR.

[StrikerRUS]

What do you think about locating Returns section before a note about custom function, like it's done in sklearn?

sklearn

dask

[jameslamb]

What do you think about locating Returns section before a note about custom function, like it's done in sklearn?

Sure, works for me!

[StrikerRUS]

Thank you!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity since it was closed. To start a new related discussion, open a new issue at https://github.com/microsoft/LightGBM/issues including a reference to this.