Add ability to specify which version of Docker image to use

[dselman]

Details

I have a project that requires the sphinx_jsdoc support which is available in the latest version of the Docker build images. However it would appear that readthedocs is currently using the 2.0 Docker build images.

Adding a YML or UI option to specify the version of the Docker build image to use would allow project to test experimental features, and for my project to use jsdoc.

• Project URL: https://readthedocs.org/projects/accordcicero/
• Build URL (if applicable): https://readthedocs.org/projects/accordcicero/builds/6341163/
• Read the Docs username (if applicable): dselman

Expected Result

• Specify the latest tag in .readthedocs.yml
• The latest Docker image is used
• The build can use sphinx_js and jsdoc

Actual Result

Build fails because the sphinx_js extension requires jsdoc to be installed and on the path.

[dselman]

Related issues:

• https://github.com/erikrose/sphinx-js/issues/35
• Add JSDoc to docs build environment #3069

[humitos]

There is a form at http://docs.readthedocs.io/en/latest/yaml-config.html#python-version where you can request to use the latest image builder.

[ericholscher]

My thoughts:

• We should add a docker_image option to readthedocs.yml, which allows 1.0, 2.0, latest as defined here: https://github.com/rtfd/readthedocs-docker-images/blob/master/CONTRIBUTING.rst#releases
• The docker_image constrain the python:version, so that if you set 3.6 Python we ensure the proper docker image is selected

This leaves us open for creating more custom docker images in the future, if we find it useful!

[ericholscher]

Will do a PR with this now.

[agjohnson]

👍

Also s/docker_image/build_image/ to match our nomenclature.

[ericholscher]

Initial PR's:

• Add the ability to add a docker config image readthedocs-build#33
• Add docker image from the YAML config integration #3339