Split trigger_build to be able to prepare_build first

Added a ``ImportWizard.trigger_initial_build`` method to be override
from corporate site.

Also, instead of using ``trigger_build`` to create the Celery task and
call it immediately, split it to use ``prepare_build`` first to create
the task and use ``trigger_build`` to effectively triggers it.

Author: humitos

common

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """Common utilty functions."""
 
 from __future__ import absolute_import
@@ -16,7 +17,7 @@
 from future.backports.urllib.parse import urlparse
 from celery import group, chord
 
-from readthedocs.builds.constants import LATEST
+from readthedocs.builds.constants import LATEST, BUILD_STATE_TRIGGERED
 from readthedocs.doc_builder.constants import DOCKER_LIMITS
 
 
@@ -75,37 +76,48 @@ def cname_to_slug(host):
     return slug
 
 
-def trigger_build(project, version=None, record=True, force=False):
+def prepare_build(
+        project, version=None, record=True, force=False, immutable=True):
     """
-    Trigger build for project and version.
+    Prepare a build in a Celery task for project and version.
+
+    If project has a ``build_queue``, execute the task on this build queue. If
+    project has ``skip=True``, the build is not triggered.
 
-    If project has a ``build_queue``, execute task on this build queue. Queue
-    will be prefixed with ``build-`` to unify build queue names.
+    :param project: project's documentation to be built
+    :param version: version of the project to be built. Default: ``latest``
+    :param record: whether or not record the build in a new Build object
+    :param force: build the HTML documentation even if the files haven't changed
+    :param immutable: whether or not create an immutable Celery signature
+    :returns: Celery signature of UpdateDocsTask to be executed
     """
     # Avoid circular import
     from readthedocs.projects.tasks import UpdateDocsTask
     from readthedocs.builds.models import Build
 
     if project.skip:
+        log.info(
+            'Build not triggered because Project.skip=True: project=%s',
+            project.slug,
+        )
         return None
 
     if not version:
         version = project.versions.get(slug=LATEST)
 
-    kwargs = dict(
-        pk=project.pk,
-        version_pk=version.pk,
-        record=record,
-        force=force,
-    )
+    kwargs = {
+        'pk': project.pk,
+        'version_pk': version.pk,
+        'record': record,
+        'force': force,
+    }
 
-    build = None
     if record:
         build = Build.objects.create(
             project=project,
             version=version,
             type='html',
-            state='triggered',
+            state=BUILD_STATE_TRIGGERED,
             success=True,
         )
         kwargs['build_pk'] = build.pk
@@ -120,16 +132,38 @@ def trigger_build(project, version=None, record=True, force=False):
         if project.container_time_limit:
             time_limit = int(project.container_time_limit)
     except ValueError:
-        pass
+        log.warning('Invalid time_limit for project: %s', project.slug)
+
     # Add 20% overhead to task, to ensure the build can timeout and the task
     # will cleanly finish.
     options['soft_time_limit'] = time_limit
     options['time_limit'] = int(time_limit * 1.2)
 
-    update_docs = UpdateDocsTask()
-    update_docs.apply_async(kwargs=kwargs, **options)
+    update_docs_task = UpdateDocsTask()
+    return update_docs_task.si(kwargs=kwargs, **options)
+
 
-    return build
+def trigger_build(project, version=None, record=True, force=False):
+    """
+    Trigger a Build.
+
+    Helper that calls ``prepare_build`` and just effectively trigger the Celery
+    task to be executed by a worker.
+
+    :param project: project's documentation to be built
+    :param version: version of the project to be built. Default: ``latest``
+    :param record: whether or not record the build in a new Build object
+    :param force: build the HTML documentation even if the files haven't changed
+    :returns: Celery AsyncResult promise
+    """
+    update_docs_task = prepare_build(
+        project,
+        version,
+        record,
+        force,
+        immutable=True,
+    )
+    return update_docs_task.apply_async()
 
 
 def send_email(recipient, subject, template, template_html, context=None,

readthedocs/core/utils/__init__.py

@@ -233,10 +233,16 @@ def done(self, form_list, **kwargs):
                 setattr(project, field, value)
         project.save()
         project_import.send(sender=project, request=self.request)
-        trigger_build(project)
+        self.trigger_initial_build(project)
         return HttpResponseRedirect(
             reverse('projects_detail', args=[project.slug]))
 
+    def trigger_initial_build(self, project):
+        """
+        Trigger initial build.
+        """
+        return trigger_build(project)
+
     def is_advanced(self):
         """Determine if the user selected the `show advanced` field."""
         data = self.get_cleaned_data_for_step('basics') or {}