Adopt the Sphinx versionadded directive

[rcomer]

Prompted by a question on Met Office Viva Engage where the user was unable to use the use_year_at_season_start parameter of add_season_year, as they had Iris v3.7.

Sphinx provides a directive to indicate when a function or parameter was added, the versionadded directive.

Example in Matplotlib renders like this.

I note that Matplotlib has only been using this for a few versions and has not attempted to go back and retrospectively add the directive for older functionality.

[bjlittle]

@rcomer I've been using this directive on geovista since inception to signpost the version when functionality was first introduced.

I think it's a valuable piece of documentation metadata for both the user and developer 👍

Note that, I've decided to not bother with the maintenance overhead of using the versionchanged directive. TBH I don't think the benefit is worth the effort.

[trexfeathers]

@bjlittle raises a good point. To have helped the Met Office user we would have needed to either used versionchanged, or provide versionadded for every parameter of a function. So far our experience in GeoVista has been versionadded only for whole operations.

I have wondered whether this could be automated, but I haven't done any investigation.

[trexfeathers]

From @scitools/peloton: In the absence of automation, we would probably need to add this to the pull request checklist (which sometimes gets ignored), and rely on reviewers to pick up on missing directives.