readthedocs.org: Improve build error/warning suggestions

Currently, we are duplicating throwing an error logic in our build tips, along with the pattern of using logic in templates to determine this. There are two areas that we can improve on to provide a more useful pattern.

For example, a build is failed when we detect a failure state in the build task. This build is then recorded with the failure text and an exit code. On view, we are duplicating this logic, searching for a reason for failure. I think the build should be updated on failure with enough information that the view or template can simply reference the error.

For example, some vaguely psuedo python:

class BuildDetailView(View):
   
    # This can be automatic with the help of a meta class on BuildException
    ERROR_MAP = {
        501: ProjectImportError,
        ...
    }
 
    def get_context_data(self, **kwargs):
        ctx = super()
        ....
        # There are a few way to do this, maybe exit code is not a good idea. Build errors
        # would have explicit exit codes for referencing the error though
        try:
            error = self.ERROR_MAP[project.exit_code]
            # Load from template, or pass into build detail template somehow
            suggestion = error.get_suggestion()
        except KeyError, AttributeError:
            pass
        return ctx

We also need to add a field to the build model to track the error code. This will be used to reverse the suggestion. Build exceptions should have a get_suggestion() method and perhaps some easy method of templating out new suggestions.

This will accomplish:

• Deduplication of this logic
• Moving error display logic out of templates
• Ties exception to suggestion

---

Update:

To summarize what we are discussing doing here, and to maybe provide a little additional context to this change:

• We want a way to emit warning messages from builds, and therefore multiple warning/error messages. The error should not just be a string model field
• The code above isn’t exactly necessary. It tries to modularize error message, but we could just as easily emit a JSON error object with both an error id and error message. The key takeaway here is that error messages have some metadata or context that the templates can use. Ultimately, the build error message should just (loosely) be a template like {% for error in build.errors %}<div class="{{ error.class }}">{{ error.message }}</div>{% endfor %}