readthedocs.org: YAML config: errors are not clear enough for users

Details

I configured .readthedocs.yaml with:

build:
  tools:
    python: 3.11

Expected Result

Nothing unusual.

Actual Result

I got the error message:

Problem in your project’s configuration. Invalid “build.tools.python”: expected one of (2.7, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, pypy3.7, pypy3.8, pypy3.9, miniconda3-4.7, mambaforge-4.10, 3), got 3.11

Despite the confusing message “expected 3.11, got 3.11”, I realized the latter was probably a float instead of a string.

The workaround was simple:

build:
  tools:
    python: "3.11"

But it can potentially be a huge time waster for someone not familiar with the pitfalls of yaml parsing. It would be nice if the parsing was more robust against this kind of type issues. Or the documentation explicitly told to use quotes.

Oh, Norway problem, you ask? See https://hitchdev.com/strictyaml/why/implicit-typing-removed/

About this issue

Original URL
State: closed
Created a year ago
Comments: 16 (16 by maintainers)

Most upvoted comments

Agreed. I feel like we’ve addressed a few issues here in a few ways. If there are any more issues with the configuration file, we will address this individually at this point.

agjohnson on Mar 26, 2024

We made our error messages a clearer. They are not perfect still, tho, but I’m tempted to close this issue at this point since there are no clear directions here and the issue from the description was already fixed. Besides, we have created an issue per problem for those that are more important. See the list at https://github.com/readthedocs/readthedocs.org/issues/10985#issuecomment-1886680779

humitos on Mar 26, 2024

These last two are a slightly different issue, and are a change/bug where project notifications are only visible for the maintainer users.

The beta instances doesn’t have this change yet, the error is clearer there: https://beta.readthedocs.org/projects/test-builds/builds/23531844/

agjohnson on Feb 22, 2024

Another error is that when using node, we require users to specify a python version too. The error isn’t clear about this.

stsewd on Sep 14, 2023

Yes. We have to improve the error message we expose to users to be more friendly 😄 . We have a few issues about this already. This is the code where we should give the users more context about what has happened: https://github.com/readthedocs/readthedocs.org/blob/1b32d18231a28022caf3c7aeb605abd850780a7b/readthedocs/config/validation.py#L15-L28

humitos on Jun 30, 2023