Add schema for configuration file with yamale

readthedocs/rtd_tests/fixtures/spec/v2/schema.yml

@@ -28,6 +28,7 @@ submodules: include('submodules', required=False)
 # Redirects for the current version to be built
 # Key/value list, represent redirects of type `type`
 # from url -> to url
+# Default: null
 redirects: map(enum('page'), map(str(), str()), required=False)
 
 ---
@@ -47,9 +48,11 @@ python:
   version: enum('2', '2.7', '3', '3.5', '3.6', required=False)
 
   # The path to the requirements file from the root of the project
+  # Default: null
   requirements: path(required=False)
 
   # Install the project using python setup.py install or pip
+  # Default: null
   install: enum('pip', 'setup.py', required=False)
 
   # Extra requirements sections to install in addition to the package dependencies
@@ -60,13 +63,24 @@ python:
   # Default: false
   system_packages: bool(required=False)
 
-sphinx:  
+sphinx:
   # The path to the conf.py file
   # Default: rtd will try to find it
   configuration: path(required=False)
 
+  # Add the -W option to sphinx-build
+  # Default: false
+  fail_on_warning: bool(required=False)
+
 mkdocs:
-  # Something
+  # The path to the mkdocs.yml file
+  # Default: rtd will try to find it
+  configuration: path(required=False)
+
+  # Add the --strict optio to mkdocs build
+  # Default: false
+  fail_on_warning: bool(required=False)
+
 
 submodules:
   # List of submodules to be included

readthedocs/rtd_tests/tests/test_yml_schema.py

@@ -2,19 +2,20 @@
 
 import pytest
 from readthedocs.rtdyml import BuildConfig
-from readthedocs.rtd_tests.utils import apply_fs
+from readthedocs_build.testing import utils
 
 
 def create_yaml(tmpdir, content):
     fs = {
         'environment.yml': '',
+        'mkdocs.yml': '',
         'rtd.yml': content,
         'docs': {
             'conf.py': '',
             'requirements.txt': '',
         },
     }
-    apply_fs(tmpdir, fs)
+    utils.apply_fs(tmpdir, fs)
     return path.join(tmpdir.strpath, 'rtd.yml')
 
 
@@ -192,7 +193,7 @@ def test_python_version_invalid(tmpdir):
     )
 
 
-def test_no_python_version(tmpdir):
+def test_python_version_no_key(tmpdir):
     content = '''
 version: "2"
 python:
@@ -201,7 +202,7 @@ def test_no_python_version(tmpdir):
     assertValidConfig(tmpdir, content)
 
 
-def test_valid_requirements(tmpdir):
+def test_python_requirements(tmpdir):
     content = '''
 version: "2"
 python:
@@ -210,7 +211,7 @@ def test_valid_requirements(tmpdir):
     assertValidConfig(tmpdir, content)
 
 
-def test_invalid_requirements_file(tmpdir):
+def test_python_requirements_invalid(tmpdir):
     content = '''
 version: "2"
 python:
@@ -223,6 +224,15 @@ def test_invalid_requirements_file(tmpdir):
     )
 
 
+def test_python_requirements_null(tmpdir):
+    content = '''
+version: "2"
+python:
+  requirements: null
+    '''
+    assertValidConfig(tmpdir, content)
+
+
 @pytest.mark.parametrize('value', ['pip', 'setup.py'])
 def test_python_install(tmpdir, value):
     content = '''
@@ -247,6 +257,15 @@ def test_python_install_invalid(tmpdir):
     )
 
 
+def test_python_install_null(tmpdir):
+    content = '''
+version: "2"
+python:
+  install: null
+    '''
+    assertValidConfig(tmpdir, content)
+
+
 def test_python_extra_requirements(tmpdir):
     content = '''
 version: "2"
@@ -273,6 +292,16 @@ def test_python_extra_requirements_invalid(tmpdir):
     )
 
 
+@pytest.mark.parametrize('value', ['', 'null', '[]'])
+def test_python_extra_requirements_empty(tmpdir, value):
+    content = '''
+version: "2"
+python:
+  extra_requirements: {value}
+    '''
+    assertValidConfig(tmpdir, content.format(value=value))
+
+
 @pytest.mark.parametrize('value', ['true', 'false'])
 def test_python_system_packages(tmpdir, value):
     content = '''
@@ -300,6 +329,15 @@ def test_python_system_packages_invalid(tmpdir, value):
 def test_sphinx(tmpdir):
     content = '''
 version: "2"
+sphinx:
+  configuration: docs/conf.py
+    '''
+    assertValidConfig(tmpdir, content)
+
+
+def test_sphinx_default_value(tmpdir):
+    content = '''
+version: "2"
 sphinx:
   file: docs/conf.py  # Default value for configuration key
     '''
@@ -320,6 +358,84 @@ def test_sphinx_invalid(tmpdir, value):
     )
 
 
+def test_sphinx_fail_on_warning(tmpdir):
+    content = '''
+version: "2"
+sphinx:
+  fail_on_warning: true
+    '''
+    assertValidConfig(tmpdir, content)
+
+
+@pytest.mark.parametrize('value', ['not true', "''", '[]'])
+def test_sphinx_fail_on_warning_invalid(tmpdir, value):
+    content = '''
+version: "2"
+sphinx:
+  fail_on_warning: {value}
+    '''
+    assertInvalidConfig(
+        tmpdir,
+        content.format(value=value),
+        ['is not a bool']
+    )
+
+
+def test_mkdocs(tmpdir):
+    content = '''
+version: "2"
+mkdocs:
+  configuration: mkdocs.yml
+    '''
+    assertValidConfig(tmpdir, content)
+
+
+def test_mkdocs_default_value(tmpdir):
+    content = '''
+version: "2"
+mkdocs:
+  file: mkdocs.yml  # Default value for configuration key
+    '''
+    assertValidConfig(tmpdir, content)
+
+
+@pytest.mark.parametrize('value', ['2', 'environment.py'])
+def test_mkdocs_invalid(tmpdir, value):
+    content = '''
+version: "2"
+mkdocs:
+  configuration: {value}
+    '''
+    assertInvalidConfig(
+        tmpdir,
+        content,
+        ['is not a path']
+    )
+
+
+def test_mkdocs_fail_on_warning(tmpdir):
+    content = '''
+version: "2"
+mkdocs:
+  fail_on_warning: true
+    '''
+    assertValidConfig(tmpdir, content)
+
+
+@pytest.mark.parametrize('value', ['not true', "''", '[]'])
+def test_mkdocs_fail_on_warning_invalid(tmpdir, value):
+    content = '''
+version: "2"
+mkdocs:
+  fail_on_warning: {value}
+    '''
+    assertInvalidConfig(
+        tmpdir,
+        content.format(value=value),
+        ['is not a bool']
+    )
+
+
 def test_submodules_include(tmpdir):
     content = '''
 version: "2"
@@ -374,7 +490,7 @@ def test_redirects(tmpdir):
     assertValidConfig(tmpdir, content)
 
 
-def test_invalid_redirects(tmpdir):
+def test_redirects_invalid(tmpdir):
     content = '''
 version: "2"
 redirects:
@@ -386,3 +502,12 @@ def test_invalid_redirects(tmpdir):
         content,
         ['is not a str']
     )
+
+
+@pytest.mark.parametrize('value', ['', 'null', '{}'])
+def test_redirects_empty(tmpdir, value):
+    content = '''
+version: "2"
+redirects: {value}
+    '''
+    assertValidConfig(tmpdir, content.format(value=value))

readthedocs/rtd_tests/utils.py

@@ -121,21 +121,6 @@ def make_test_hg():
     return directory
 
 
-def apply_fs(tmpdir, contents):
-    """
-    Create the directory structure specified in ``contents``. It's a dict of
-    filenames as keys and the file contents as values. If the value is another
-    dict, it's a subdirectory.
-    """
-    for filename, content in contents.items():
-        if hasattr(content, 'items'):
-            apply_fs(tmpdir.mkdir(filename), content)
-        else:
-            file = tmpdir.join(filename)
-            file.write(content)
-    return tmpdir
-
-
 def create_user(username, password, **kwargs):
     user = new(User, username=username, **kwargs)
     user.set_password(password)

readthedocs/rtdyml/__init__.py

@@ -1,3 +1,5 @@
+"""Validator for the RTD configuration file."""
+
 from os import path
 
 import six
@@ -12,8 +14,12 @@
 
 
 class PathValidator(Validator):
+
     """
-    Docstring
+    Path validator
+
+    Checks if the given value is a string and a existing
+    file.
     """
 
     tag = 'path'
@@ -32,19 +38,22 @@ def _is_valid(self, value):
 
 class BuildConfig(object):
 
+    """Wrapper object to validate to configuration file."""
+
     def __init__(self, configuration_file):
         self.configuration_file = configuration_file
         self.data = yamale.make_data(self.configuration_file)
         self.schema = yamale.make_schema(
             V2_SCHEMA,
-            validators=self.get_validators()
+            validators=self._get_validators()
         )
 
-    def get_validators(self):
+    def _get_validators(self):
         validators = DefaultValidators.copy()
         PathValidator.configuration_file = self.configuration_file
         validators[PathValidator.tag] = PathValidator
         return validators
 
     def validate(self):
+        """Validate the current configuration file."""
         return yamale.validate(self.schema, self.data)