11# Authors: The scikit-learn developers
22# SPDX-License-Identifier: BSD-3-Clause
33
4- from sklearn ._config import get_config
4+ import itertools
5+
6+ from ... import __version__
7+ from ..._config import get_config
8+ from ..fixes import parse_version
9+
10+
11+ class _HTMLDocumentationLinkMixin :
12+ """Mixin class allowing to generate a link to the API documentation.
13+
14+ This mixin relies on three attributes:
15+ - `_doc_link_module`: it corresponds to the root module (e.g. `sklearn`). Using this
16+ mixin, the default value is `sklearn`.
17+ - `_doc_link_template`: it corresponds to the template used to generate the
18+ link to the API documentation. Using this mixin, the default value is
19+ `"https://scikit-learn.org/{version_url}/modules/generated/
20+ {estimator_module}.{estimator_name}.html"`.
21+ - `_doc_link_url_param_generator`: it corresponds to a function that generates the
22+ parameters to be used in the template when the estimator module and name are not
23+ sufficient.
24+
25+ The method :meth:`_get_doc_link` generates the link to the API documentation for a
26+ given estimator.
27+
28+ This useful provides all the necessary states for
29+ :func:`sklearn.utils.estimator_html_repr` to generate a link to the API
30+ documentation for the estimator HTML diagram.
31+
32+ Examples
33+ --------
34+ If the default values for `_doc_link_module`, `_doc_link_template` are not suitable,
35+ then you can override them and provide a method to generate the URL parameters:
36+ >>> from sklearn.base import BaseEstimator
37+ >>> doc_link_template = "https://address.local/{single_param}.html"
38+ >>> def url_param_generator(estimator):
39+ ... return {"single_param": estimator.__class__.__name__}
40+ >>> class MyEstimator(BaseEstimator):
41+ ... # use "builtins" since it is the associated module when declaring
42+ ... # the class in a docstring
43+ ... _doc_link_module = "builtins"
44+ ... _doc_link_template = doc_link_template
45+ ... _doc_link_url_param_generator = url_param_generator
46+ >>> estimator = MyEstimator()
47+ >>> estimator._get_doc_link()
48+ 'https://address.local/MyEstimator.html'
49+
50+ If instead of overriding the attributes inside the class definition, you want to
51+ override a class instance, you can use `types.MethodType` to bind the method to the
52+ instance:
53+ >>> import types
54+ >>> estimator = BaseEstimator()
55+ >>> estimator._doc_link_template = doc_link_template
56+ >>> estimator._doc_link_url_param_generator = types.MethodType(
57+ ... url_param_generator, estimator)
58+ >>> estimator._get_doc_link()
59+ 'https://address.local/BaseEstimator.html'
60+ """
61+
62+ _doc_link_module = "sklearn"
63+ _doc_link_url_param_generator = None
64+
65+ @property
66+ def _doc_link_template (self ):
67+ sklearn_version = parse_version (__version__ )
68+ if sklearn_version .dev is None :
69+ version_url = f"{ sklearn_version .major } { sklearn_version .minor }
70+ else :
71+ version_url = "dev"
72+ return getattr (
73+ self ,
74+ "__doc_link_template" ,
75+ (
76+ f"https://scikit-learn.org/{ version_url }
77+ "{estimator_module}.{estimator_name}.html"
78+ ),
79+ )
80+
81+ @_doc_link_template .setter
82+ def _doc_link_template (self , value ):
83+ setattr (self , "__doc_link_template" , value )
84+
85+ def _get_doc_link (self ):
86+ """Generates a link to the API documentation for a given estimator.
87+
88+ This method generates the link to the estimator's documentation page
89+ by using the template defined by the attribute `_doc_link_template`.
90+
91+ Returns
92+ -------
93+ url : str
94+ The URL to the API documentation for this estimator. If the estimator does
95+ not belong to module `_doc_link_module`, the empty string (i.e. `""`) is
96+ returned.
97+ """
98+ if self .__class__ .__module__ .split ("." )[0 ] != self ._doc_link_module :
99+ return ""
100+
101+ if self ._doc_link_url_param_generator is None :
102+ estimator_name = self .__class__ .__name__
103+ # Construct the estimator's module name, up to the first private submodule.
104+ # This works because in scikit-learn all public estimators are exposed at
105+ # that level, even if they actually live in a private sub-module.
106+ estimator_module = "." .join (
107+ itertools .takewhile (
108+ lambda part : not part .startswith ("_" ),
109+ self .__class__ .__module__ .split ("." ),
110+ )
111+ )
112+ return self ._doc_link_template .format (
113+ estimator_module = estimator_module , estimator_name = estimator_name
114+ )
115+ return self ._doc_link_template .format (** self ._doc_link_url_param_generator ())
5116
6117
7118class ReprHTMLMixin :
8119 @property
9120 def _repr_html_ (self ):
10- # Taken from sklearn.base.BaseEstimator
11121 """HTML representation of estimator.
12122 This is redundant with the logic of `_repr_mimebundle_`. The latter
13123 should be favored in the long term, `_repr_html_` is only
@@ -22,15 +132,11 @@ def _repr_html_(self):
22132 return self ._repr_html_inner
23133
24134 def _repr_html_inner (self ):
25- from sklearn .utils ._repr_html .params import _html_template
26-
27- return _html_template (self )
135+ return self ._html_repr ()
28136
29137 def _repr_mimebundle_ (self , ** kwargs ):
30138 """Mime bundle used by jupyter kernels to display estimator"""
31- from sklearn .utils ._repr_html .params import _html_template
32-
33139 output = {"text/plain" : repr (self )}
34140 if get_config ()["display" ] == "diagram" :
35- output ["text/html" ] = _html_template ( self )
141+ output ["text/html" ] = self . _html_repr ( )
36142 return output
0 commit comments