Repository: readthedocs/readthedocs.org

Issue:
If mkdocs.yml is broken raise a specific exception and catch it properly
Currently, we are raising `BuildEnvironmentError` which is too generic and produce the error to be logged into sentry when it's not an app bug but a user configuration problem.

https://github.com/rtfd/readthedocs.org/blob/df85fefc5f59c7a00bcc1ffe23965efe75e8c895/readthedocs/doc_builder/backends/mkdocs.py#L84-L87

We should raise something like `MkDocsYAMLError` (or a better name) and add it as a warning exception at,

https://github.com/rtfd/readthedocs.org/blob/df85fefc5f59c7a00bcc1ffe23965efe75e8c895/readthedocs/doc_builder/environments.py#L433-L441


Discussion:

Resolving patch:
diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -15,7 +15,7 @@
 from django.template import loader as template_loader
 
 from readthedocs.doc_builder.base import BaseBuilder
-from readthedocs.doc_builder.exceptions import BuildEnvironmentError
+from readthedocs.doc_builder.exceptions import MkDocsYAMLParseError
 from readthedocs.projects.models import Feature
 
 log = logging.getLogger(__name__)
@@ -99,7 +99,7 @@ def load_yaml_config(self):
             if hasattr(exc, 'problem_mark'):
                 mark = exc.problem_mark
                 note = ' (line %d, column %d)' % (mark.line + 1, mark.column + 1)
-            raise BuildEnvironmentError(
+            raise MkDocsYAMLParseError(
                 'Your mkdocs.yml could not be loaded, '
                 'possibly due to a syntax error{note}'.format(note=note)
             )
diff --git a/readthedocs/doc_builder/environments.py b/readthedocs/doc_builder/environments.py
--- a/readthedocs/doc_builder/environments.py
+++ b/readthedocs/doc_builder/environments.py
@@ -37,7 +37,7 @@
 from .exceptions import (
     BuildEnvironmentCreationFailed, BuildEnvironmentError,
     BuildEnvironmentException, BuildEnvironmentWarning, BuildTimeoutError,
-    ProjectBuildsSkippedError, VersionLockedError, YAMLParseError)
+    ProjectBuildsSkippedError, VersionLockedError, YAMLParseError, MkDocsYAMLParseError)
 
 log = logging.getLogger(__name__)
 
@@ -438,6 +438,7 @@ class BuildEnvironment(BaseEnvironment):
         ProjectBuildsSkippedError,
         YAMLParseError,
         BuildTimeoutError,
+        MkDocsYAMLParseError
     )
 
     def __init__(self, project=None, version=None, build=None, config=None,
diff --git a/readthedocs/doc_builder/exceptions.py b/readthedocs/doc_builder/exceptions.py
--- a/readthedocs/doc_builder/exceptions.py
+++ b/readthedocs/doc_builder/exceptions.py
@@ -7,7 +7,6 @@
 
 
 class BuildEnvironmentException(Exception):
-
     message = None
     status_code = None
 
@@ -21,7 +20,6 @@ def get_default_message(self):
 
 
 class BuildEnvironmentError(BuildEnvironmentException):
-
     GENERIC_WITH_BUILD_ID = ugettext_noop(
         'There was a problem with Read the Docs while building your documentation. '
         'Please report this to us with your build id ({build_id}).',
@@ -29,32 +27,33 @@ class BuildEnvironmentError(BuildEnvironmentException):
 
 
 class BuildEnvironmentCreationFailed(BuildEnvironmentError):
-
     message = ugettext_noop('Build environment creation failed')
 
 
 class VersionLockedError(BuildEnvironmentError):
-
     message = ugettext_noop('Version locked, retrying in 5 minutes.')
     status_code = 423
 
 
 class ProjectBuildsSkippedError(BuildEnvironmentError):
-
     message = ugettext_noop('Builds for this project are temporarily disabled')
 
 
 class YAMLParseError(BuildEnvironmentError):
-
     GENERIC_WITH_PARSE_EXCEPTION = ugettext_noop(
         'Problem parsing YAML configuration. {exception}',
     )
 
 
 class BuildTimeoutError(BuildEnvironmentError):
-
     message = ugettext_noop('Build exited due to time out')
 
 
 class BuildEnvironmentWarning(BuildEnvironmentException):
     pass
+
+
+class MkDocsYAMLParseError(BuildEnvironmentError):
+    GENERIC_WITH_PARSE_EXCEPTION = ugettext_noop(
+        'Problem parsing MkDocs YAML configuration. {exception}',
+    )


Test patch: