Migrate to ` .readthedocs.yaml` configuration

[qstokkink]

I received the following e-mail from ReadTheDocs:

We are removing the "use system packages" feature on August 29th. Make sure you are installing all the required dependecies to build your project's documentation using a requirements.txt file and specifying it in your .readthedocs.yaml.

This is still fine: we don't use EDIT: we DO use a .readthedocs.yaml and instead we use the ReadTheDocs settings. However, on the admin panel it states:

Usage of the below settings is deprecated and support for these fields will be removed on September 25th, 2023.

For more information, see our blog post: migrating your configuration to .readthedocs.yaml.

We'll have to migrate EDIT: whatever settings are left before September 25th, 2023 or our docs stop working.

[qstokkink]

This is a screenshot of our deprecated settings:

[qstokkink]

I believe the settings above are ported as follows:

sphinx:
  builder: dirhtml
  configuration: doc/conf.py

python:
  install:
    - requirements: requirements.txt

build:
  tools:
    python: "3"

formats:
  - epub
  - pdf

Our current .readthedocs.yaml is ALMOST equivalent:

version: 2

formats: all

# Check https://docs.readthedocs.io/en/stable/config-file/v2.html#build-image
# Current highest stable version is 3.7 (update as needed)
python:
  version: "3.7"
  install:
    - requirements: doc/requirements.txt
    - requirements: requirements.txt

sphinx:
  builder: html
  configuration: doc/conf.py
  fail_on_warning: false

I see two differences:

1. The yaml file is missing build.tools.python: "3".
2. The default settings use sphinx.builder: dirhtml instead of builder: html (current).

From the build logs it seems that (1) Python 3.7 is automatically picked based on our python.version and (2) our html setting is overwriting the default htmldir setting. Both (1) and (2) are therefore apparently inconsequential.

With that, I think we can assume that this deprecation can safely happen and we need no further action.