Reference Issues/PRs

The release of scikit-learn v1.3.0 two days ago (link) included the addition of new public methods for metadata routing, specifically #24027.

That change broke documentation generation in LightGBM (https://github.com/microsoft/LightGBM), and I suspect it might affect other projects which implement scikit-learn-compatible estimators similarly. The LightGBM-specific details are documented in microsoft/LightGBM#5954 (comment), but I've included the relevant points below.

What does this implement/fix? Explain your changes.

Proposes removing reStructuredText :ref: references to scikit-learn's own documentation in public methods of classes which are intended to be inherited from by other libraries.

In LightGBM, we follow the advice in "Developing scikit-learn estimators" (link) and inherit from sklearn.base.BaseEstimator, sklearn.base.ClassifierMixin, and sklearn.base.RegressorMixin to reduce boilerplate and keep up with changes here in scikit-learn.

#24027 introduced reStructuredText references in public methods of those classes which only resolve correctly when rendered inside scikit-learn's own docs, like this:

In LightGBM, we use sphinx.ext.autodoc to generate documentation of the lightgbm Python package, e.g. https://lightgbm.readthedocs.io/en/latest/pythonapi/lightgbm.LGBMClassifier.html#. And we set the following in our Sphinx configuration (code link)

autodoc_default_options = {
    "members": True,
    "inherited-members": True,
    "show-inheritance": True,
}

With that combination, sphinx.ext.autodoc automatically includes the rendered docstrings for every class attribute and method which doesn't begin with a _, including those inherited from the class's parent classes. That means as of scikit-learn v1.3.0, Sphinx will try to render method documentation for e.g. lightgbm.sklearn.LGBMClassifier.get_metadata_routing.

Because of the scikit-learn-docs-specific references in scikit-learn's docstrings, that can lead to docs-generation errors like the following:

Warning, treated as error:
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of lightgbm.dask.DaskLGBMClassifier:1:undefined label: 'metadata_routing'

Any other comments?

I suspect that the setup for LightGBM that I've described is one that other projects implementing scikit-learn-compatible estimators might have for their documentation + strategy for remaining compatible. That's why I think a change to the docs here in scikit-learn is preferable to the following things I could do in LightGBM to work around this:

• explicitly add all the new APIs like get_metadata_routing and the set_*_request() methods, and define new docstrings on them, in lightgbm's source code
• create references in lightgbm's Sphinx docs which catch those references like :ref:User Guide <metadata_routing> and re-route out to the relevant page(s) at https://scikit-learn.org/

Since the things in sklearn.base are expected to be imported by other projects creating scikit-learn-compatible estimators, specifically to reduce such boilerplate and duplicate effort across downstream projects, I think they should be free from docs references which assume they're being rendered inside scikit-learn's own documentation.

Thanks very much for your time and consideration.