make sphinx directive about version more sklearn specific

[Remi-Gau]

Describe the issue linked to the documentation

This is minor issue mostly affecting the rendering of the documentation of downstream libraries.

For example in Nilearn we use the TransformerMixin in quite a few of our estimators.

But when viewing the doc of our estimators, the sklearn methods of that mixin may have things like 'Added in version 1.3'

https://nilearn.github.io/stable/modules/generated/nilearn.maskers.SurfaceLabelsMasker.html#nilearn.maskers.SurfaceLabelsMasker.set_transform_request

However Nilearn does not have a version 1.3 so this kind of look confusing.

Suggest a potential alternative/fix

I am wondering if it would be possible to mention 'scikit-learn' in the sphinx directives that are about version (added, deprecated...)

[Remi-Gau]

Note this is neither super important nor urgent.

But if this is something that would be possible I can take care of updating the directives.

[ogrisel]

I agree that this is annoying. sphinx does not seems to be very specific about the format of the values used in this directive:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded

Maybe it's fine to replace ..versionchanged:: 1.7 by ..versionchanged:: scikit-learn 1.7 in docstrings of public base classes of scikit-learn that are meant to be derived in third-party libraries?

Maybe we should open a discussion on the sphinx repo itself, as this problem might have been resolved elsewhere already.

[Remi-Gau]

Maybe it's fine to replace ..versionchanged:: 1.7 by ..versionchanged:: scikit-learn 1.7 in docstrings of public base classes of scikit-learn that are meant to be derived in third-party libraries?

I was actually of doing something similar in our own library (..versionchanged:: nilearn 0.12.0) in case someone inherits from our own classes.