Previous situation¶

The Docker images used by our builders were based on Ubuntu 18.04. Recently, we added a new feature to install custom system packages, which allowed many projects to have better control of their build process without having to use conda to manage non-Python dependencies.

However, this Ubuntu version was released three years ago and, even though it was good enough for most projects, we have been receiving requests to upgrade certain system packages over the years. Since these are managed through the operating system package manager, and we do not provide a way to add custom Personal Package Archives, such upgrades were not possible.

Many Python projects use a secondary programming language for a variety of reasons. Established compiled languages like C, C++, and FORTRAN have readily available compilers that will work for the majority of use cases. However, other younger technologies move at a faster pace, and developers often want specific versions of the toolchains that cannot be installed with the system package manager. This affected projects that combine backend and frontend code that need Node.js to compile their JavaScript sources, such as Jupyter extensions, and libraries with performance-critical code written in Rust or Go.

We have often suggested specifying custom versions of non-Python dependencies using conda, to specify custom versions of non-Python dependencies, but this requires learning another tool that might be unfamiliar for some projects.

New build YAML configuration¶

To overcome all these problems, we have added a new configuration value, build.tools, that receive a dictionary of toolchain versions. This new configuration requires specifying the base image name in build.os, currently ubuntu-20.04. Our configuration documentation contains a simple example:

version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
    # You can also specify other tool versions:
    # nodejs: "16"
    # rust: "1.55"
    # golang: "1.17"

And you can draw inspiration from some community projects that are using this feature already:

• cryptography, the reference Python library for cryptographic algorithms, can now specify the Rust version required to build the package.

• parsel, a Python library to manipulate HTML and XML using XPath and CSS selectors, leverages the new specification to build their documentation on the just released Python 3.10.

• Thebe, a Jupyter-powered tool to make HTML pages interactive, needs Node.js to build the latest version of the code.

Do you think this feature will be useful for you as well? Give it a try and let us know.

Remember you can always see the latest changes to our platforms in our Read the Docs Changelog.

—

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!