Read the Docs がビルドしてくれなくなったときの対処法 (2023/10/16-) (The configuration key "build.os" is required ...)

Python パッケージのドキュメンテーションに Read the Docs を利用している方であって、2023年10月に「何もしていないのに Read the Docs が以下のエラーを吐いてドキュメントをビルドしてくれなくなった」という方向けです。

The configuration key "build.os" is required to build your documentation. 
Read more at https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os

エラーメッセージにしたがえばよいですが、素直にしたがっていくと修正が3回発生した (私は) のでメモです。

参考文献

• Use build.os instead of build.image on your configuration file — Read the Docs Blog
  • 1回目のビルドエラーのメッセージで検索するとヒットするページで、なるほど 2023/10/16 以降には設定ファイルに build.os キーがなければならないとあります。
• Sphinx Read-The-Docs Theme recognised but not "found" - Stack Overflow
  • 3回目のビルドエラーのメッセージで検索するとヒットするページで、pip install sphinx-rtd-theme せよとあります (これまでは明示的に設定ファイルでインストールを指示する必要はありませんでした)。
• Configuration file v2 (.readthedocs.yaml) — Read the Docs user documentation
  • .readthedocs.yaml のドキュメントで、各キーの意味や python.version は廃止される旨が書いてあります。

対処法

以下の 3 点を対応したらビルドできました (私は)。

• .readthedocs.yaml の build.os キーにドキュメントをビルドする OS を指定します。
  • "ubuntu-20.04" か "ubuntu-22.04" を指定するようです。
• .readthedocs.yaml に build.tools.python キーに Python のバージョンを指定すると共に、廃止された python.version キーを削除します。
• conf.py で html_theme = 'sphinx_rtd_theme' としている場合、sphinx-rtd-theme の明示的なインストールが必要になったので、pyproject.toml の pyproject.optional-dependencies に適当なキー名 (下図では docs) で依存性を追加し、.readthedocs.yaml でそのキーを指定します。
  • pyproject.toml でなく setup.py などを利用している方は extras_require になると思います (Optional dependencies)

私の場合のファイル差分は以下です。

補足: エラーメッセージ

約3ヶ月ぶりにパッケージをメンテナンスしたらドキュメントがビルドされませんでした。 build.os キーがないといわれていました (1回目)。

The configuration key "build.os" is required to build your documentation. 
Read more at https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os

なのでこのページを参考に build 以下を設定しました。すると python.version キーは無効だといわれました (2回目)。

Problem in your project's configuration. 
Invalid configuration option "python.version": Make sure the key name is correct.

なので python.version キーを削除しました。すると 'sphinx_rtd_theme' はないといわれました (3回目)。

We encountered a problem with a command while building your project. 
To resolve this error, double check your project configuration and 
installed dependencies are correct and have not changed recently.

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

なので pyproject.optional-dependencies で対応したところ、パッケージのドキュメントがビルドできました (以下)。
https://cookies-utilities.readthedocs.io/en/latest/