Add feature flipping models to Projects, plus example feature flip

Also, use a new pattern for API instance objects

Because we're returning a list of feature keys, which is a many2many field, we
can't use the Project class as we were using it. For instance, this is
impossible in Django, because the m2m field requires saving first:

    proj = Project(features=[Feature(feature='foo')], ...)

    # or

    proj = Project(...)
    proj.features.add(Feature(feature='foo'))

This might make the modeling around API model objects more grokable

Author: agjohnson

readthedocs/doc_builder/python_environments.py

@@ -11,6 +11,7 @@
 from readthedocs.doc_builder.config import ConfigWrapper
 from readthedocs.doc_builder.loader import get_builder_class
 from readthedocs.projects.constants import LOG_TEMPLATE
+from readthedocs.projects.models import Feature
 
 log = logging.getLogger(__name__)
 
@@ -128,8 +129,14 @@ def install_core_requirements(self):
         if self.project.documentation_type == 'mkdocs':
             requirements.append('mkdocs==0.15.0')
         else:
-            requirements.extend(['sphinx==1.5.3', 'sphinx-rtd-theme<0.3',
-                                 'readthedocs-sphinx-ext<0.6'])
+            if self.project.has_feature(Feature.USE_SPHINX_LATEST):
+                requirements.append('sphinx<1.7')
+            else:
+                requirements.append('sphinx==1.5.6')
+            requirements.extend([
+                'sphinx-rtd-theme<0.3',
+                'readthedocs-sphinx-ext<0.6'
+            ])
 
         cmd = [
             'python',

readthedocs/projects/admin.py

@@ -14,7 +14,7 @@
 from readthedocs.notifications.views import SendNotificationView
 
 from .notifications import ResourceUsageNotification
-from .models import (Project, ImportedFile,
+from .models import (Project, ImportedFile, Feature,
                      ProjectRelationship, EmailHook, WebHook, Domain)
 from .tasks import remove_dir
 
@@ -180,8 +180,14 @@ class DomainAdmin(admin.ModelAdmin):
     model = Domain
 
 
+class FeatureAdmin(admin.ModelAdmin):
+    model = Feature
+    filter_horizontal = ('projects',)
+
+
 admin.site.register(Project, ProjectAdmin)
 admin.site.register(ImportedFile, ImportedFileAdmin)
 admin.site.register(Domain, DomainAdmin)
+admin.site.register(Feature, FeatureAdmin)
 admin.site.register(EmailHook)
 admin.site.register(WebHook)

readthedocs/projects/migrations/0019_add-feature-flags.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.9.12 on 2017-10-05 01:21
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('projects', '0018_fix-translation-model'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Feature',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('feature', models.CharField(max_length=32, unique=True, verbose_name='Project feature tag')),
+                ('description', models.TextField(blank=True, null=True, verbose_name='Description')),
+            ],
+        ),
+        migrations.AddField(
+            model_name='feature',
+            name='projects',
+            field=models.ManyToManyField(blank=True, related_name='features', to='projects.Project'),
+        ),
+    ]

readthedocs/projects/migrations/0020_add-feature-latest-sphinx.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.9.12 on 2017-10-05 01:06
+from __future__ import unicode_literals
+
+from django.db import migrations
+
+
+FEATURE = 'use_sphinx_latest'
+DESCRIPTION = 'Use latest Sphinx version'
+
+
+def add_feature(apps, schema_editor):
+    Feature = apps.get_model('projects', 'Feature')
+    (_, created) = Feature.objects.get_or_create(
+        feature=FEATURE,
+        description=DESCRIPTION
+    )
+
+
+def remove_feature(apps, schema_editor):
+    Feature = apps.get_model('projects', 'Feature')
+    Feature.objects.filter(feature=FEATURE).delete()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('projects', '0019_add-feature-flags'),
+    ]
+
+    operations = [
+        migrations.RunPython(add_feature, remove_feature)
+    ]

readthedocs/projects/models.py

@@ -821,6 +821,35 @@ def add_comment(self, version_slug, page, content_hash, commit, user, text):
                                      hash=content_hash, commit=commit)
         return node.comments.create(user=user, text=text)
 
+    def has_feature(self, feature):
+        """Does project have existing feature flag"""
+        return self.features.filter(feature=feature).exists()
+
+
+class APIProject(Project):
+
+    """Project object from API data deserialization
+
+    This is to preserve the Project model methods for use in builder instances.
+    Properties can be read only here, as the builders don't need write access to
+    a number of attributes.
+    """
+
+    features = []
+
+    class Meta:
+        proxy = True
+
+    def __init__(self, *args, **kwargs):
+        self.features = kwargs.pop('features', [])
+        super(APIProject, self).__init__(*args, **kwargs)
+
+    def save(self, *args, **kwargs):
+        return 0
+
+    def has_feature(self, feature):
+        return feature in self.features
+
 
 @python_2_unicode_compatible
 class ImportedFile(models.Model):
@@ -921,3 +950,30 @@ def delete(self, *args, **kwargs):  # pylint: disable=arguments-differ
         from readthedocs.projects import tasks
         broadcast(type='app', task=tasks.symlink_domain, args=[self.project.pk, self.pk, True])
         super(Domain, self).delete(*args, **kwargs)
+
+
+@python_2_unicode_compatible
+class Feature(models.Model):
+
+    """Project feature flags"""
+
+    # Feature constants - this is not a exhaustive list of features, features
+    # are arbitrary and maintained via data migrations.
+
+    #: Use latest Sphinx
+    USE_SPHINX_LATEST = 'use_sphinx_latest'
+
+    projects = models.ManyToManyField(
+        Project,
+        related_name='features',
+        blank=True,
+    )
+    feature = models.CharField(
+        _('Project feature tag'),
+        max_length=32,
+        unique=True,
+    )
+    description = models.TextField(_('Description'), blank=True, null=True)
+
+    def __str__(self):
+        return self.description or self.feature

readthedocs/projects/utils.py

@@ -192,11 +192,10 @@ def make_api_version(version_data):
 
 def make_api_project(project_data):
     """Make mock Project instance from API return"""
-    from readthedocs.projects.models import Project
+    from readthedocs.projects.models import APIProject
     for key in ['users', 'resource_uri', 'absolute_url', 'downloads',
                 'main_language_project', 'related_projects']:
         if key in project_data:
             del project_data[key]
-    project = Project(**project_data)
-    project.save = _new_save
+    project = APIProject(**project_data)
     return project

readthedocs/restapi/serializers.py

@@ -1,13 +1,13 @@
 """Defines serializers for each of our models."""
 
 from __future__ import absolute_import
-from builtins import object
 
+from builtins import object
 from rest_framework import serializers
 
 from readthedocs.builds.models import Build, BuildCommandResult, Version
-from readthedocs.projects.models import Project, Domain
 from readthedocs.oauth.models import RemoteOrganization, RemoteRepository
+from readthedocs.projects.models import Project, Domain
 
 
 class ProjectSerializer(serializers.ModelSerializer):
@@ -28,6 +28,18 @@ class Meta(object):
 
 class ProjectAdminSerializer(ProjectSerializer):
 
+    """Project serializer for admin only access
+
+    Includes special internal fields that don't need to be exposed through the
+    general API, mostly for fields used in the build process
+    """
+
+    features = serializers.SlugRelatedField(
+        many=True,
+        read_only=True,
+        slug_field='feature',
+    )
+
     class Meta(ProjectSerializer.Meta):
         fields = ProjectSerializer.Meta.fields + (
             'enable_epub_build',
@@ -44,6 +56,7 @@ class Meta(ProjectSerializer.Meta):
             'skip',
             'requirements_file',
             'python_interpreter',
+            'features',
         )