Add schema for configuration file with yamale

.gitignore

@@ -1,4 +1,5 @@
 *.db
+*.rdb
 *.egg-info
 *.log
 *.pyc

readthedocs/buildconfig/__init__.py

@@ -0,0 +1,187 @@
+"""Validator for the RTD configuration file."""
+
+from __future__ import division, print_function, unicode_literals
+
+from os import path
+
+import six
+import yamale
+from yamale.validators import DefaultValidators, Validator
+
+V2_SCHEMA = path.join(
+    path.dirname(__file__),
+    '../rtd_tests/fixtures/spec/v2/schema.yml'
+)
+
+ALL = 'all'
+
+DEFAULT_VALUES = {
+    'formats': [],
+    'conda': None,
+    'build': {
+        'image': '2.0',
+    },
+    'python': {
+        'version': '3.6',
+        'requirements': None,
+        'install': None,
+        'extra_requirements': [],
+        'system_packages': False,
+    },
+    'sphinx': {
+        'configuration': None,
+        'fail_on_warning': False,
+    },
+    'mkdocs': {
+        'configuration': None,
+        'fail_on_warning': False,
+    },
+    'submodules': {
+        'include': [],
+        'exclude': [],
+        'recursive': False,
+    },
+    'redirects': None,
+}
+
+CONSTRAINTS = {
+    'Documentation type': {
+        'unique': ['sphinx', 'mkdocs'],
+        'default': 'sphinx',
+    },
+    'Submodules': {
+        'unique': ['submodules.include', 'submodules.exclude'],
+        'default': 'submodules.include',
+    }
+}
+
+
+def flatten(dic, keep_key=False, position=None):
+    """
+    Returns a flattened dictionary
+
+    Given a dictionary of nested dictionaries, it returns
+    a dictionary with all nested keys at the top level.
+
+    For example
+
+    {
+        'key': 'value',
+        'nested': {
+            'subkey': 'value'
+        },
+    }
+
+    Becomes
+
+    {
+        'key': value,
+        'nested': {...},
+        'nested.subkey': 'value'
+    }
+    """
+    child = {}
+
+    for key, value in dic.items():
+        if isinstance(key, six.string_types):
+            key = key.replace('.', '_')
+        if position:
+            item_position = '{}.{}'.format(position, key)
+        else:
+            item_position = key
+
+        if isinstance(value, dict):
+            child.update(
+                flatten(dic[key], keep_key, item_position)
+            )
+            if keep_key:
+                child[item_position] = value
+        else:
+            child[item_position] = value
+
+    return child
+
+
+class PathValidator(Validator):
+
+    """
+    Path validator
+
+    Checks if the given value is a string and a existing
+    file.
+    """
+
+    tag = 'path'
+    constraints = []
+    configuration_file = '.'
+
+    def _is_valid(self, value):
+        if isinstance(value, six.string_types):
+            file_ = path.join(
+                path.dirname(self.configuration_file),
+                value
+            )
+            return path.exists(file_)
+        return False
+
+
+class BuildConfig(object):
+
+    """Wrapper object to validate to configuration file."""
+
+    _schema = V2_SCHEMA
+    _default_values = DEFAULT_VALUES
+    _constraints = CONSTRAINTS
+
+    def __init__(self, configuration_file):
+        self.configuration_file = configuration_file
+        self.data = yamale.make_data(self.configuration_file)
+        self.defaults = flatten(self._default_values, keep_key=True)
+        self.constraints = self._constraints
+        self.schema = yamale.make_schema(
+            self._schema,
+            validators=self._get_validators()
+        )
+
+    def _get_validators(self):
+        """Custom validators for yamale."""
+        validators = DefaultValidators.copy()
+        PathValidator.configuration_file = self.configuration_file
+        validators[PathValidator.tag] = PathValidator
+        return validators
+
+    def check_constraints(self):
+        """
+        Check constraints between keys.
+
+        Such as relations of uniquiness and set default values for those.
+        """
+        for subject, constraint in self.constraints.items():
+            present_keys = [
+                key
+                for key in constraint['unique']
+                if key in self.data[0]
+            ]
+            default_key = constraint.get('default')
+            if not present_keys and default_key:
+                self.data[0][default_key] = self.defaults[default_key]
+            elif len(present_keys) > 1:
+                raise ValueError(
+                    '{subject} can not have {keys} at the same time'.format(
+                        subject=subject,
+                        keys=constraint['unique'],
+                    )
+                )
+
+    def set_defaults(self):
+        """Set default values to the currently processed data."""
+        for key, value in self.defaults.items():
+            if key not in self.data[0]:
+                self.data[0][key] = value
+
+    def validate(self):
+        """Validate the current configuration file."""
+        self.check_constraints()
+        self.set_defaults()
+        yamale.validate(self.schema, self.data)
+        return self.data[0]

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

@@ -0,0 +1,96 @@
+# Read the Docs configuration file
+
+# The version of the spec to be use
+version: enum('2')
+
+# Formats of the documentation to be built
+# Default: []
+formats: any(list(enum('htmlzip', 'pdf', 'epub')), enum('all'), required=False)
+
+# Configuration for Conda support
+conda: include('conda', required=False)
+
+# Configuration for the documentation build process
+build: include('build', required=False)
+
+# Configuration of the Python environment to be used
+python: include('python', required=False)
+
+# Configuration for sphinx documentation
+sphinx: include('sphinx', required=False)
+
+# Configuration for mkdocs documentation
+mkdocs: include('mkdocs', required=False)
+
+# Submodules configuration
+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)
+
+---
+
+conda:
+  # The path to the Conda environment file from the root of the project
+  environment: path()
+
+build:
+  # The build docker image to be used
+  # Default: '2.0'
+  image: enum('1.0', '2.0', 'latest', required=False)
+
+python:
+  # The Python version
+  # Default: '3.6'
+  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
+  # Default: []
+  extra_requirements: list(str(), required=False)
+
+  # Give the virtual environment access to the global site-packages dir
+  # Default: false
+  system_packages: bool(required=False)
+
+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:
+  # 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
+  # Default: []
+  include: any(list(str()), enum('all'), required=False)
+
+  # List of submodules to be ignored
+  # Default: []
+  exclude: any(list(str()), enum('all'), required=False)
+
+  # Do a recursive clone?
+  # Default: false
+  recursive: bool(required=False)