[python-package] limit when num_boost_round warnings are emitted (fixes #6324)

[jameslamb]

Fixes #6324

Replaces #6548

• ensures that the warning about aliases for num_iterations is only raised if the user-provided configuration has conflicting values
• expands documentation about how parameters in LightGBM are merged

Notes for Reviewers

Just opening this to show I'm working on it. It still needs tests, and isn't ready for review yet.

How I tested this

Enabled this branch on readthedocs. See https://readthedocs.org/projects/lightgbm/builds/.

Isn't this kind of a lot of complexity for one parameter?

I think it's worth it. "number of boosting rounds" is one of the most important parameters for gradient boosting. I think it's worth handling it very carefully and raising an informative warning in the cases where conflicting configuration is provided. For example, I think this warning could save people from unnecessarily performing hyperparameter tuning over different combinations of num_iterations and num_trees, not understanding that those mean the same thing in LightGBM's parameters.

Why not use pytest.parametrize() for all these tests?

I started out that way, but then decided that it'd require enough if-else blocks and other logic that I was worried about accidentally, silently, mishandling some test cases.

I think the level of repetition in these test cases is ok, because it makes them easy to read and understand.

[StrikerRUS]

I like the general idea of this PR!
Left some minor comments below:

[StrikerRUS]

Thanks a lot for addressing my comments!
I have two more suggestions based on the most recent commit.

[StrikerRUS]

Thanks very much for working on this change!

[jameslamb]

Thanks for the thoughtful reviews @StrikerRUS !

[StrikerRUS]

@jameslamb Could you please remove python/alias-warning branch on RTD?

I think we don't need to leave debug builds there.

[jameslamb]

🙈 sorry about that, thanks for your attention to detail!

Just removed it.

[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.