Configuration file v2 (.readthedocs.yaml) not working with project-template

Question

Read the Docs is planning to start failing builds for not using configuration file version key 2 on September 25, 2023. I tried the following readthedocs.yaml content with the sklearn project-template and it did not work:

version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/conf.py

The error that I received :

Extension error: Could not import extension numpydoc (exception: No module named ‘numpydoc’)

Here is what I am currently using in my readthedocs.yml but it will not meet requirements in September:

formats:
  - none
requirements_file: requirements.txt
python:
  pip_install: true
  extra_requirements:
    - tests
    - docs

Does anyone have a readthedocs.yaml configuration file that they know to be working with the sklearn project-template, and will survive the September deadline?

Answer 1

The solution is to put the extra requirements listed in EXTRAS_REQUIRE from setup.py, into requirements.txt. From setup.py, the extra requirements listed here:

EXTRAS_REQUIRE = {
    'tests': [
        'pytest',
        'pytest-cov'],
    'docs': [
        'sphinx',
        'sphinx-gallery',
        'sphinx_rtd_theme',
        'numpydoc',
        'matplotlib'
    ]
} 

get added to requirements.text as:

numpy
scipy
scikit-learn
matplotlib
sphinx
pytest
setuptools
pytest
pytest-cov
sphinx
sphinx-gallery
sphinx_rtd_theme
numpydoc

Your requirements will probably be different. Then the following readthedocs.yml file allowed my read the docs build to pass with the sklearn project-template:

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"


# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: doc/conf.py

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
  install:
    - requirements: requirements.txt