FIX improve doc and test for HTMLDocumentationLinkMixin (scikit-learn#29774)

Co-authored-by: Adrin Jalali <adrin.jalali@gmail.com>

Author: glemaitre

sklearn/utils/_estimator_html_repr.py

@@ -466,15 +466,31 @@ class _HTMLDocumentationLinkMixin:
     Examples
     --------
     If the default values for `_doc_link_module`, `_doc_link_template` are not suitable,
-    then you can override them:
+    then you can override them and provide a method to generate the URL parameters:
     >>> from sklearn.base import BaseEstimator
-    >>> estimator = BaseEstimator()
-    >>> estimator._doc_link_template = "https://website.com/{single_param}.html"
+    >>> doc_link_template = "https://address.local/{single_param}.html"
     >>> def url_param_generator(estimator):
     ...     return {"single_param": estimator.__class__.__name__}
-    >>> estimator._doc_link_url_param_generator = url_param_generator
+    >>> class MyEstimator(BaseEstimator):
+    ...     # use "builtins" since it is the associated module when declaring
+    ...     # the class in a docstring
+    ...     _doc_link_module = "builtins"
+    ...     _doc_link_template = doc_link_template
+    ...     _doc_link_url_param_generator = url_param_generator
+    >>> estimator = MyEstimator()
     >>> estimator._get_doc_link()
-    'https://website.com/BaseEstimator.html'
+    'https://address.local/MyEstimator.html'
+
+    If instead of overriding the attributes inside the class definition, you want to
+    override a class instance, you can use `types.MethodType` to bind the method to the
+    instance:
+    >>> import types
+    >>> estimator = BaseEstimator()
+    >>> estimator._doc_link_template = doc_link_template
+    >>> estimator._doc_link_url_param_generator = types.MethodType(
+    ...     url_param_generator, estimator)
+    >>> estimator._get_doc_link()
+    'https://address.local/BaseEstimator.html'
     """
 
     _doc_link_module = "sklearn"
@@ -530,6 +546,4 @@ def _get_doc_link(self):
             return self._doc_link_template.format(
                 estimator_module=estimator_module, estimator_name=estimator_name
             )
-        return self._doc_link_template.format(
-            **self._doc_link_url_param_generator(self)
-        )
+        return self._doc_link_template.format(**self._doc_link_url_param_generator())

sklearn/utils/tests/test_estimator_html_repr.py

@@ -1,6 +1,7 @@
 import html
 import locale
 import re
+import types
 from contextlib import closing
 from functools import partial
 from io import StringIO
@@ -453,7 +454,9 @@ def test_html_documentation_link_mixin_sklearn(mock_version):
         ("prefix.mypackage.mymodule.submodule", "prefix.mypackage.mymodule.submodule"),
     ],
 )
-def test_html_documentation_link_mixin_get_doc_link(module_path, expected_module):
+def test_html_documentation_link_mixin_get_doc_link_instance(
+    module_path, expected_module
+):
     """Check the behaviour of the `_get_doc_link` with various parameter."""
 
     class FooBar(_HTMLDocumentationLinkMixin):
@@ -469,6 +472,32 @@ class FooBar(_HTMLDocumentationLinkMixin):
     assert est._get_doc_link() == f"https://website.com/{expected_module}.FooBar.html"
 
 
+@pytest.mark.parametrize(
+    "module_path,expected_module",
+    [
+        ("prefix.mymodule", "prefix.mymodule"),
+        ("prefix._mymodule", "prefix"),
+        ("prefix.mypackage._mymodule", "prefix.mypackage"),
+        ("prefix.mypackage._mymodule.submodule", "prefix.mypackage"),
+        ("prefix.mypackage.mymodule.submodule", "prefix.mypackage.mymodule.submodule"),
+    ],
+)
+def test_html_documentation_link_mixin_get_doc_link_class(module_path, expected_module):
+    """Check the behaviour of the `_get_doc_link` when `_doc_link_module` and
+    `_doc_link_template` are defined at the class level and not at the instance
+    level."""
+
+    class FooBar(_HTMLDocumentationLinkMixin):
+        _doc_link_module = "prefix"
+        _doc_link_template = (
+            "https://website.com/{estimator_module}.{estimator_name}.html"
+        )
+
+    FooBar.__module__ = module_path
+    est = FooBar()
+    assert est._get_doc_link() == f"https://website.com/{expected_module}.FooBar.html"
+
+
 def test_html_documentation_link_mixin_get_doc_link_out_of_library():
     """Check the behaviour of the `_get_doc_link` with various parameter."""
     mixin = _HTMLDocumentationLinkMixin()
@@ -479,7 +508,7 @@ def test_html_documentation_link_mixin_get_doc_link_out_of_library():
     assert mixin._get_doc_link() == ""
 
 
-def test_html_documentation_link_mixin_doc_link_url_param_generator():
+def test_html_documentation_link_mixin_doc_link_url_param_generator_instance():
     mixin = _HTMLDocumentationLinkMixin()
     # we can bypass the generation by providing our own callable
     mixin._doc_link_template = (
@@ -492,11 +521,30 @@ def url_param_generator(estimator):
             "another_variable": "value_2",
         }
 
-    mixin._doc_link_url_param_generator = url_param_generator
+    mixin._doc_link_url_param_generator = types.MethodType(url_param_generator, mixin)
 
     assert mixin._get_doc_link() == "https://website.com/value_1.value_2.html"
 
 
+def test_html_documentation_link_mixin_doc_link_url_param_generator_class():
+    # we can bypass the generation by providing our own callable
+
+    def url_param_generator(estimator):
+        return {
+            "my_own_variable": "value_1",
+            "another_variable": "value_2",
+        }
+
+    class FooBar(_HTMLDocumentationLinkMixin):
+        _doc_link_template = (
+            "https://website.com/{my_own_variable}.{another_variable}.html"
+        )
+        _doc_link_url_param_generator = url_param_generator
+
+    estimator = FooBar()
+    assert estimator._get_doc_link() == "https://website.com/value_1.value_2.html"
+
+
 @pytest.fixture
 def set_non_utf8_locale():
     """Pytest fixture to set non utf-8 locale during the test.