Add the ability to add a docker config image

docs/spec.rst

@@ -105,6 +105,12 @@ Following mapping keys are supported (all but the marked once are optional):
     - ``pdf``, default: ``false``
     - ``epub``, default: ``false``
 
+``build``
+  Options for setting the docker configuration.
+
+    ``image``
+    This sets the docker image to use on the build, as defined `here <https://github.com/rtfd/readthedocs-docker-images/blob/master/CONTRIBUTING.rst#releases>`_.
+
 ``python``
     Python specific configuration. All builds are executed inside a
     virtualenv. This config can customize the virtualenv before running the

readthedocs_build/config/config.py

@@ -5,12 +5,8 @@
 from .find import find_one
 from .parser import ParseError
 from .parser import parse
-from .validation import validate_bool
-from .validation import validate_choice
-from .validation import validate_directory
-from .validation import validate_file
-from .validation import validate_string
-from .validation import ValidationError
+from .validation import (validate_bool, validate_choice, validate_directory,
+                         validate_file, validate_string, ValidationError)
 
 
 __all__ = (
@@ -30,6 +26,18 @@
 TYPE_REQUIRED = 'type-required'
 PYTHON_INVALID = 'python-invalid'
 
+DOCKER_BUILD_IMAGES = {
+    '1.0': {
+        'python': {'supported_versions': [2, 2.7, 3, 3.4]},
+    },
+    '2.0': {
+        'python': {'supported_versions': [2, 2.7, 3, 3.5]},
+    },
+    'latest': {
+        'python': {'supported_versions': [2, 2.7, 3, 3.3, 3.4, 3.5, 3.6]},
+    },
+}
+
 
 class ConfigError(Exception):
 
@@ -79,6 +87,7 @@ class BuildConfig(dict):
         '"python.extra_requirements" section must be a list.')
 
     PYTHON_SUPPORTED_VERSIONS = [2, 2.7, 3, 3.3, 3.4, 3.5, 3.6]
+    DOCKER_SUPPORTED_VERSIONS = ['1.0', '2.0', 'latest']
 
     def __init__(self, env_config, raw_config, source_file, source_position):
         self.env_config = env_config
@@ -115,13 +124,6 @@ def get_valid_types(self):
             'sphinx',
         )
 
-    def get_valid_python_versions(self):
-        try:
-            return self.env_config['python']['supported_versions']
-        except (KeyError, TypeError):
-            pass
-        return self.PYTHON_SUPPORTED_VERSIONS
-
     def get_valid_formats(self):
         return (
             'none',
@@ -145,6 +147,9 @@ def validate(self):
         # Validate env_config.
         self.validate_output_base()
 
+        # Validate the build environment first
+        self.validate_build()  # Must happen before `validate_python`!
+
         # Validate raw_config. Order matters.
         self.validate_name()
         self.validate_type()
@@ -205,6 +210,23 @@ def validate_base(self):
             base = validate_directory(base, base_path)
         self['base'] = base
 
+    def validate_build(self):
+        # Defaults
+        build = {'image': '2.0'}
+        if 'build' in self.raw_config:
+            _build = self.raw_config['build']
+            if 'image' in _build:
+                with self.catch_validation_error('build'):
+                    build['image'] = validate_choice(
+                        str(_build['image']),
+                        self.DOCKER_SUPPORTED_VERSIONS,
+                    )
+        self['build'] = build
+
+        # Set the valid python versions for this container
+        img = build['image']
+        self.PYTHON_SUPPORTED_VERSIONS = DOCKER_BUILD_IMAGES[img]['python']['supported_versions']
+
     def validate_python(self):
         python = {
             'use_system_site_packages': False,
@@ -280,7 +302,7 @@ def validate_python(self):
                                 pass
                     python['version'] = validate_choice(
                         version,
-                        self.get_valid_python_versions()
+                        self.PYTHON_SUPPORTED_VERSIONS
                     )
 
         self['python'] = python

readthedocs_build/config/test_config.py

@@ -281,23 +281,6 @@ def it_validates_wrong_type_right_value():
         build.validate_python()
         assert build['python']['version'] == 3
 
-    def it_validates_env_supported_versions():
-        build = get_build_config(
-            {'python': {'version': 3.6}},
-            env_config={'python': {'supported_versions': [3.5]}}
-        )
-        with raises(InvalidConfig) as excinfo:
-            build.validate_python()
-        assert excinfo.value.key == 'python.version'
-        assert excinfo.value.code == INVALID_CHOICE
-
-        build = get_build_config(
-            {'python': {'version': 3.6}},
-            env_config={'python': {'supported_versions': [3.5, 3.6]}}
-        )
-        build.validate_python()
-        assert build['python']['version'] == 3.6
-
 
 def describe_validate_formats():
 
@@ -413,6 +396,70 @@ def it_fails_if_base_does_not_exist(tmpdir):
         assert excinfo.value.code == INVALID_PATH
 
 
+def describe_validate_build():
+
+    def it_fails_if_build_is_invalid_option(tmpdir):
+        apply_fs(tmpdir, minimal_config)
+        build = BuildConfig(
+            {},
+            {'build': {'image': 3.0}},
+            source_file=str(tmpdir.join('readthedocs.yml')),
+            source_position=0)
+        with raises(InvalidConfig) as excinfo:
+            build.validate_build()
+        assert excinfo.value.key == 'build'
+        assert excinfo.value.code == INVALID_CHOICE
+
+    def it_fails_on_python_validation(tmpdir):
+        apply_fs(tmpdir, minimal_config)
+        build = BuildConfig(
+            {},
+            {
+                'build': {'image': 1.0},
+                'python': {'version': '3.3'},
+            },
+            source_file=str(tmpdir.join('readthedocs.yml')),
+            source_position=0)
+        build.validate_build()
+        with raises(InvalidConfig) as excinfo:
+            build.validate_python()
+        assert excinfo.value.key == 'python.version'
+        assert excinfo.value.code == INVALID_CHOICE
+
+    def it_works_on_python_validation(tmpdir):
+        apply_fs(tmpdir, minimal_config)
+        build = BuildConfig(
+            {},
+            {
+                'build': {'image': 'latest'},
+                'python': {'version': '3.3'},
+            },
+            source_file=str(tmpdir.join('readthedocs.yml')),
+            source_position=0)
+        build.validate_build()
+        build.validate_python()
+
+    def it_works(tmpdir):
+        apply_fs(tmpdir, minimal_config)
+        build = BuildConfig(
+            {},
+            {'build': {'image': 'latest'}},
+            source_file=str(tmpdir.join('readthedocs.yml')),
+            source_position=0)
+        build.validate_build()
+        assert build['build']['image'] == 'latest'
+
+    def default(tmpdir):
+        apply_fs(tmpdir, minimal_config)
+        build = BuildConfig(
+            {},
+            {},
+            source_file=str(tmpdir.join('readthedocs.yml')),
+            source_position=0)
+        build.validate_build()
+        assert build['build']['image'] == '2.0'
+
+
 def test_build_validate_calls_all_subvalidators(tmpdir):
     apply_fs(tmpdir, minimal_config)
     build = BuildConfig(

requirements/tests.txt

@@ -1,5 +1,5 @@
 mock==1.3.0
-pytest>=2.7
-pytest-describe>=0.10.1
+pytest==3.2.5
+pytest-describe==0.11.0
 pytest-xdist>=1.12
 tox>=2.1