Better error message when using build.tools.python without build.os

[adamjstewart]

Details

• Read the Docs project URL: https://readthedocs.org/projects/fiscalyear/
• Build URL (if applicable): https://readthedocs.org/projects/fiscalyear/builds/16068109/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/adamjstewart/

Expected Result

I would expect the following simple .readthedocs.yaml file to work:

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

# Required
version: 2

# Set the version of Python
build:
  tools:
    python: "3.10"

# Configuration for Sphinx documentation
sphinx:
   configuration: docs/conf.py
   fail_on_warning: true

Actual Result

I see the following build error:

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

For now I'll just remove this option.

[choi-jiwoo]

Had same issue when building documentation of my project, and found out that I had to configure build.os before build.tools. It is stated as a Required field in their documentation.

See the documentation about build.os here.

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

# Required
version: 2

# Set the version of Python
build:
  os: ubuntu-20.04  # <- add this line
  tools:
    python: "3.10"

# Configuration for Sphinx documentation
sphinx:
   configuration: docs/conf.py
   fail_on_warning: true

[adamjstewart]

Hmm, is there any reason that build.os needs to be required to use build.tools? There's only one option at the moment and I'm not sure if most users will care what version of Linux they build on.

[humitos]

Hi! Yeah, build.os is required as you already figured it out. However, the error message should be clearer and communicate this in a better way. @stsewd is there an easy way to add this check to run before the build.tools.python and update the error message?

Note that I created a branch in test-builds to test this. See the build output at https://readthedocs.org/projects/test-builds/builds/16080135/

is there any reason that build.os needs to be required to use build.tools?

In simple words, having a default here has avoided us to move forward in the past. We experienced similar issues with build.image that defaulted to latest and because of that we weren't able to touch latest image anymore because it always breaks someone's else project.

[stsewd]

Yes, it should be possible to provide a better message

[adamjstewart]

In simple words, having a default here has avoided us to move forward in the past. We experienced similar issues with build.image that defaulted to latest and because of that we weren't able to touch latest image anymore because it always breaks someone's else project.

But presumably if I don't specify builds.os or build.tools I'm still getting some default image, right? Why should the requirements be any different if I also want to specify build.tools? Other CI platforms like GitHub Actions allow me to select ubuntu-latest so that I can test my package against newer OSes.

[humitos]

Other CI platforms like GitHub Actions allow me to select ubuntu-latest so that I can test my package against newer OSes.

We have an open issue for this at #8861 where you can read and comment about the discussion.

[cjw296]

Why is build.os required at all? I write libraries that are OS agnostic, so why can't a "default" OS be in place? (likely "latest ubuntu").

[humitos]

@cjw296 the process to build the documentation itself has to run on a OS. We used the approach of having a "default OS" in the past and it's more problematic than useful to the large scale of users we have. We think that explicitly defining the dependencies is good practice and helps people to create reproducible builds over time.

[humitos]

build.tools.python is no longer required. You can only one of the other tools now. See an example only using build.tools.nodejs at https://beta.readthedocs.org/projects/test-builds/builds/23326369/

Also, we have improved this message as well:

I think this issue is already solved. Feel free to re-open if you consider.

[adamjstewart]

Looks like there is an ubuntu-lts-latest option now for people who always want to run with the latest ubuntu version 😄