Invalid configuration build.tools.python #9635

Details

• Read the Docs project URL: https://readthedocs.org/projects/jaracodevelop/
• Build URL (if applicable): https://readthedocs.org/projects/jaracodevelop/builds/18216684/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/jaraco/

Expected Result

According to the docs, I've added a build.tools.python to the config.

When I do, the build fails fast with this error:

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

I'm not sure how to make sure the key name is correct. It looks correct to me. It matches the heading in the docs.

Actual Result

It should just work or it should provide a better error message about what expectation was missed. The suggestion to check the key name is unhelpful when it matches a valid key name.

I suspect there may be an undocumented dependency, either on the order of keys in the config or perhaps an os must be supplied to indicate a tools.python.

Aha. I do see now that build.os is "required". Which is weird, because it wasn't required before. Sure would be nice if there was a way not to have to specify the OS in order to specify a Python version.

In that case, the error message should be something like "required key 'build.os' missing". Better, though, would be to decouple these concerns so it's possible to simply override the Python version (especially while users are forced to specify Python versions due to #9623).