Deprecate mf_flag call signature in xclim.ensembles, expose calendar conversion utilities, fix _gen_returns_section bug

[Zeitsperre]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR fixes [PyOpenSci] Reviewer #1 Comments #1305
• Tests for the changes have been added (for bug fixes / features)
  • (If applicable) Documentation has been added / updated (for bug fixes / features)
• CHANGES.rst has been updated (with summary of main changes)
  • Link to issue (:issue:number) and pull request (:pull:number) has been added

What kind of change does this PR introduce?

• Changes the call signature for xclim.ensembles.create_ensemble() and _ens_align_datasets() to use multifile in lieu of mf_flag.
• Updates docstrings and emits warnings for deprecated usage on those call signatures.
• Exposes two previously private functions that can return day of year indexes explicitly or randomly.
• Moves the module docstring from xclim.indices into the indices documentation file.
• Fixes a formatting bug in _gen_returns_section that caused poor rendering in the documentation

Does this PR introduce a breaking change?

No*. Original calls with kwargs mf_flag set will still work, but will emit warnings that users should update their scripts. This will be a major breaking change in xclim v0.43.0. The new functions were previously inaccessible (not breaking).

Other information:

[Zeitsperre]

Question: Should I deal with the other API-related comment in this PR?

Other example is xclim.core.convert_calendar. It has 2 private functions (_yearly_interp_doy, _yearly_random_doy) that could be out of the main function. This makes the if statements easier to follow due to the code has a very large if statement.

[bzah]

LGTM!
There are not too many changes here, so from a reviewer pov I would not mind if you also included the other API changes in the same PR.

[Zeitsperre]

This PR is good for review!

[aulemahal]

Agreed!
We had the same Future vs Deprecation issue in xscen this morning...

[Zeitsperre]

Returns formatting for Indicators is improved:

[aulemahal]

Way better than before, thanks!
Ze best would be to have a second bullet point level for the "description" attribute I think, really struggled to find how to do this when I implemented this part. But this is already much more readable.