[ci] [docs] sphinx builds failing on scikit-learn links: "CRITICAL: Unexpected section title"

## Description

Docs builds started failing a few days ago with many instances of this:

> ------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

That is causing the readthedocs builds and CI checks to fail. It should be fixed.

## Reproducible example

See any recent run of:

* the `Static Analysis` workflow (https://github.com/microsoft/LightGBM/actions/workflows/static_analysis.yml)
* readthedocs builds: https://app.readthedocs.org/projects/lightgbm/builds/

<details><summary>full logs (click me)</summary>

From a recent build on `master` ([build link](https://github.com/microsoft/LightGBM/actions/runs/16486937288/job/46648967605))

```text
...
reading sources... [100%] pythonapi/lightgbm.train
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:52: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:31: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:58: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:49: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/dask.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:31: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:64: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:31: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:70: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:70: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:61: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:46: CRITICAL: Unexpected section title.

Returns
------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:26: CRITICAL: Unexpected section title.

Parameters
---------- [docutils]
/home/runner/work/LightGBM/LightGBM/python-package/lightgbm/sklearn.py:docstring of sklearn.utils._metadata_requests.RequestMethod.__get__.<locals>.func:31: CRITICAL: Unexpected section title.

Returns
------- [docutils]
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... 
Writing evaluated template result to /home/runner/work/LightGBM/LightGBM/docs/_build/html/_static/documentation_options.js
Writing evaluated template result to /home/runner/work/LightGBM/LightGBM/docs/_build/html/_static/language_data.js
Writing evaluated template result to /home/runner/work/LightGBM/LightGBM/docs/_build/html/_static/basic.css
Writing evaluated template result to /home/runner/work/LightGBM/LightGBM/docs/_build/html/_static/js/versions.js
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [  2%] Advanced-Topics
writing output... [  5%] C-API
writing output... [  7%] Development-Guide
writing output... [  9%] Experiments
writing output... [ 12%] FAQ
writing output... [ 14%] Features
writing output... [ 16%] GPU-Performance
writing output... [ 19%] GPU-Targets
writing output... [ 21%] GPU-Tutorial
writing output... [ 23%] GPU-Windows
writing output... [ 26%] Installation-Guide
writing output... [ 28%] Parallel-Learning-Guide
writing output... [ 30%] Parameters
writing output... [ 33%] Parameters-Tuning
writing output... [ 35%] Python-API
writing output... [ 37%] Python-Intro
writing output... [ 40%] Quick-Start
writing output... [ 42%] README
writing output... [ 44%] gcc-Tips
writing output... [ 47%] index
writing output... [ 49%] pythonapi/lightgbm.Booster
writing output... [ 51%] pythonapi/lightgbm.CVBooster
writing output... [ 53%] pythonapi/lightgbm.DaskLGBMClassifier
writing output... [ 56%] pythonapi/lightgbm.DaskLGBMRanker
writing output... [ 58%] pythonapi/lightgbm.DaskLGBMRegressor
writing output... [ 60%] pythonapi/lightgbm.Dataset
writing output... [ 63%] pythonapi/lightgbm.LGBMClassifier
writing output... [ 65%] pythonapi/lightgbm.LGBMModel
writing output... [ 67%] pythonapi/lightgbm.LGBMRanker
writing output... [ 70%] pythonapi/lightgbm.LGBMRegressor
writing output... [ 72%] pythonapi/lightgbm.Sequence
writing output... [ 74%] pythonapi/lightgbm.create_tree_digraph
writing output... [ 77%] pythonapi/lightgbm.cv
writing output... [ 79%] pythonapi/lightgbm.early_stopping
writing output... [ 81%] pythonapi/lightgbm.log_evaluation
writing output... [ 84%] pythonapi/lightgbm.plot_importance
writing output... [ 86%] pythonapi/lightgbm.plot_metric
writing output... [ 88%] pythonapi/lightgbm.plot_split_value_histogram
writing output... [ 91%] pythonapi/lightgbm.plot_tree
writing output... [ 93%] pythonapi/lightgbm.record_evaluation
writing output... [ 95%] pythonapi/lightgbm.register_logger
writing output... [ 98%] pythonapi/lightgbm.reset_parameter
writing output... [100%] pythonapi/lightgbm.train
generating indices... genindex done
highlighting module code... [ 17%] lightgbm.basic
highlighting module code... [ 33%] lightgbm.callback
highlighting module code... [ 50%] lightgbm.dask
highlighting module code... [ 67%] lightgbm.engine
highlighting module code... [ 83%] lightgbm.plotting
highlighting module code... [100%] lightgbm.sklearn
writing additional pages... search done
copying images... [ 14%] _static/images/level-wise.png
copying images... [ 29%] _static/images/leaf-wise.png
copying images... [ 43%] _static/images/gpu-performance-comparison.png
copying images... [ 57%] _static/images/artifacts-not-available.svg
copying images... [ 71%] _static/images/dask-initial-setup.svg
copying images... [ 86%] _static/images/dask-concat.svg
copying images... [100%] logo/LightGBM_logo_black_text.svg
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 40 warnings (with warnings treated as errors).
make: *** [Makefile:20: html] Error 1
make: Leaving directory '/home/runner/work/LightGBM/LightGBM/docs'
Error: Process completed with exit code 1.
```

</details>

## Environment info

Latest `master` (https://github.com/microsoft/LightGBM/commit/a0fde1b00d40eb664945aeaca8c9159ff872206b)

## Additional Comments

I strongly suspect that this is related to the release of `scikit-learn` 1.7.1 one week ago: https://pypi.org/project/scikit-learn/1.7.1/

Haven't reviewed it yet, but it looks like a related issue was raised in `scikit-learn` (https://github.com/scikit-learn/scikit-learn/issues/31804) and a PR went up to fix it (https://github.com/scikit-learn/scikit-learn/pull/31805).

If that looks like a permanent fix, maybe we can just add a `!=1.7.1` in the docs environment here and be done with this... I will test that in a bit.

In case it helps, see a previous case where `scikit-learn` metadata routing docs broke LightGBM's docs builds: https://github.com/microsoft/LightGBM/issues/5954


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ci] [docs] sphinx builds failing on scikit-learn links: "CRITICAL: Unexpected section title" #6978

Description

Reproducible example

Environment info

Additional Comments

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[ci] [docs] sphinx builds failing on scikit-learn links: "CRITICAL: Unexpected section title" #6978

Description

Description

Reproducible example

Environment info

Additional Comments

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions