`readthedocs/build:latest` is outdated

[akihironitta]

Report

readthedocs/build:latest that is available on hub.docker.com was pushed at Feb 18, 2020 at 10:49 am and is very outdated.

Question

With our configuration, which docker image is used by the readthedocs with our configuration? Is it one of the images that are publicly available on hub.docker.com or somewhere else?

build:
  os: ubuntu-20.04
  tools:
    python: "3.9"

https://github.com/Lightning-AI/lightning/blob/61c28cb428a13c2aea6d7f3f55e0f00431a4ea4e/.readthedocs.yml#L41-L48

Background

We've been using readthedocs/build:latest, but we've recently observed that building our docs fails only in our CI (https://github.com/Lightning-AI/lightning/pull/13547), and thus, we'd like to use one of your docker images to build the docs in our CI to avoid potential issues that may raised by any difference in the environment between our CI and readthedocs' CD although I'm aware that it's not meant to be used for building our docs as stated in your README:

These images are only for internal usage on Read the Docs project. They are not meant to build your documentation locally, to replace Read the Docs' service or to emulate it locally.

[humitos]

Hi, the following configuration

build: os: ubuntu-20.04

will use this Docker image: https://hub.docker.com/layers/build/readthedocs/build/ubuntu-20.04-2022.02.16/images/sha256-cbe6e6e8339567e6e38fb612feee7f73ae15d1684ec241b565af73e740dbcfb6?context=explore

we'd like to use one of your docker images to build the docs in our CI to avoid potential issues that may raised by any difference in the environment between our CI and readthedocs' CD

Instead of doing this, you can just enable the PR builder in your project and let Read the Docs to build your project on each PR, reporting the status back to GitHub and blocking the merge if it fails for any reason. This way, there won't be surprises when merging the PR into the main branch. Take a look at https://docs.readthedocs.io/en/stable/pull-requests.html

[akihironitta]

Hi @humitos, thank you for your swift reply.

you can just enable the PR builder in your project and let Read the Docs to build your project on each PR, reporting the status back to GitHub and blocking the merge if it fails for any reason. This way, there won't be surprises when merging the PR into the main branch. Take a look at https://docs.readthedocs.io/en/stable/pull-requests.html

I'm sorry I missed the doc section. I wasn't aware of that, and I should've found it before creating this issue. I'll try your suggestion instead of creating our own workflow.

Thank you very much for taking your time and sharing this information.

[ascillitoe]

Hi @humitos. The PR builder works great for us for the alibi and alibi-detect libraries, and is very helpful in allowing us to preview the rendered docs. However, we also build the docs manually in our own CI because we need to check the PDF build passes. This CI has recently been failing since ubuntu-18.04 is being deprecated as a GitHub runner.

It would be great if the PR builder could add inbuilt support for other builds apart from HTML, but in the mean time, is there anywhere we can access a more recent image? Or is there another recommended approach to test non-html builds in CI?

Thanks in advance!

Edit: p.s. I tried using the ubuntu-22.04-2022.03.15 image. However, it seems this is not as complete as the 7.0 image, and is not selectable in .readthedocs.yml so prevents us from accurately emulating the RTD build.

[humitos]

Hi @ascillitoe!

It would be great if the PR builder could add inbuilt support for other builds apart from HTML,

I'd suggest you to open an issue at https://github.com/readthedocs/readthedocs.org/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc if it doesn't already exist. This is something we have talked in the past but it was not implemented for some reasons (at that time).

in the mean time, is there anywhere we can access a more recent image? Or is there another recommended approach to test non-html builds in CI?

Note that the Docker images built from this repository are not intended to be used outside the Read the Docs build process executed by the application. We do not provide support for that.

Edit: p.s. I tried using the ubuntu-22.04-2022.03.15 image. However, it seems this is not as complete as the 7.0 image, and is not selectable in .readthedocs.yml so prevents us from accurately emulating the RTD build.

The most recent image is the one you linked here. That's what we are using on the application when executing builds. If you want to upgrade your own CI to check the PDF, that's the image you should use.

On Read the Docs, you can select that image using build.os in your config file: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os