Add default args in Trainer methods doc

[rasbt]

What does this PR do?

Added the default values in the Trainer method parameter docstrings where it was missing. I think this makes reading the docs easier.

Btw. maybe it would be better to have a consistent rule/style for this? E.g., I like how scikit-learn is doing it

    Parameters
    ----------
    estimator : estimator instance
        An unfitted estimator.

    n_features_to_select : "auto", int or float, default='warn'
        If `"auto"`, the behaviour depends on the `tol` parameter:

        - if `tol` is not `None`, then features are selected until the score
          improvement does not exceed `tol`.
        - otherwise, half of the features are selected.

        If integer, the parameter is the absolute number of features to select.
        If float between 0 and 1, it is the fraction of features to select.

        .. versionadded:: 1.1
           The option `"auto"` was added in version 1.1.

        .. deprecated:: 1.1
           The default changed from `None` to `"warn"` in 1.1 and will become
           `"auto"` in 1.3. `None` and `'warn'` will be removed in 1.3.
           To keep the same behaviour as `None`, set
           `n_features_to_select="auto" and `tol=None`.

    tol : float, default=None
        If the score is not incremented by at least `tol` between two
        consecutive feature additions or removals, stop adding or removing.
        `tol` is enabled only when `n_features_to_select` is `"auto"`.

but maybe we can discuss this in a separate issue/PR

Does your PR introduce any breaking changes? If yes, please list them.

None

Before submitting

• Was this discussed/approved via a GitHub issue? (not for typos and docs)
• Did you read the contributor guideline, Pull Request section?
• Did you make sure your PR does only one thing, instead of bundling different changes together?
• Did you make sure to update the documentation with your changes? (if necessary)
• Did you write any new necessary tests? (not for typos and docs)
• Did you verify new and existing tests pass locally with your changes?
• Did you list all the breaking changes introduced by this pull request?
• Did you update the CHANGELOG? (not for typos, docs, test updates, or internal minor changes/refactorings)

PR review

Anyone in the community is welcome to review the PR.
Before you start reviewing make sure you have read Review guidelines. In short, see the following bullet-list:

• Is this pull request ready for review? (if not, please submit in draft mode)
• Check that all items from Before submitting are resolved
• Make sure the title is self-explanatory and the description concisely explains the PR
• Add labels and milestones (and optionally projects) to the PR so it can be classified

Did you have fun?

Make sure you had fun coding 🙃

[awaelchli]

Hello @rasbt
Currently, the sphinx doc generator adds the default values automatically to the rendered docs page based on the default values specified in the signature. We have discussed manually adding these for each parameter in the past, like you did here. The maintenance effort is higher: when a default value changes, it needs to be updated manually in the docstring too. But considering that the trainer defaults don't change very often, and it is sometimes hard to read the docs, I am fine with either way :)

For the rest of the code base, I would let sphinx handle the defaults.

[rasbt]

Thanks for the note @awaelchli

I totally agree with you regarding the maintenance efforts. If it can be added automatically, this would be awesome. I was wondering if this is possible with Sphinx (I know that scikit-learn for example still adds the defaults manually, and I thought there was maybe a limitation in Sphinx)?

Right now it looks like that the defaults don't show up in the parameter docstrings:

They are only in the call sig above:

Or is this what you mean? As a user, I find it very painful to scroll up and down and look for the defaults. It would be nice to have the defaults mentioned in the parameter descriptions. But maybe this shouldn't be done manually like you said, and we could think about a more maintainable solution automating this.

[tchaton]

Nice addition! Thanks. Even if the maintenance effort is higher, I believe the Trainer should be fully documented.

[stale]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. If you need further help see our docs: https://pytorch-lightning.readthedocs.io/en/latest/generated/CONTRIBUTING.html#pull-request or ask the assistance of a core contributor here or on Slack. Thank you for your contributions.

[rasbt]

Just to bump this up. Any ideas how we should best go about this? I think ideally we want some automatic solution. The question is, does it exist? Maybe not in Sphix, but it might be possible to write a parser doing this. But maybe more a long- rather than short-term solution.

Looking at other well maintained packages like scikit-learn, it looks like people still do this manually.

[awaelchli]

@rasbt Automatic solutions won't work well because defaults are often chosen at runtime because they depend on the setting of other arguments. This is especially true for the Trainer which has so many arguments. Another example is #11950 where an argument gets set to default None simply to detect internally whether the user has explicitly set a value or not, but the value None is never used in the end. We will always have to describe such cases in words :)

[rasbt]

Haha, was just about to apply those. LGTM. Thanks, Adrian.