Add user doc on what to do on common build failures

[agjohnson]

Doc should be a more prominent doc than our FAQ and should include things like:

• When a build fails due to time out or memory constraints, what can I do? The common solution here is to reduce usage
  • You can mock out dependencies instead of installing and using the dependencies (we have a FAQ entry that is mostly hidden and needs to be expanded).
  • The next might be avoiding installation and imports altogether and using sphinx-autoapi to document your code.
  • Lastly, open a support issue to get more resources.
• On a general failure, we should document that this is an error on our side and we need to either surface a user-facing error message or we need to fix a problem with our servers. Users should file an issue on our issue tracker send us an email with the build id (see Move community support to email #5651)
• Configuration file errors. For most of the errors, I think we can link to our docs on the actual schema. These will define in good detail how to use the config file. There are probably a few errors that could be called out though.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[humitos]

Anthony documented more cases at #5256 that should be considered here also.

[humitos]

I'm marking this issue as a Good First Issue since it's not "too complicated" to do it.

The FAQ that Anthony mention in the description is this guide: https://docs.readthedocs.io/en/latest/guides/build-using-too-many-resources.html

In fact, I think it would be good to add a mention to sphinx-autoapi to that guide for users that are documenting the source code API.

[astrojuanlu]

Also:

• Fail if more than one config file is present

[humitos]

@benjaoming pinging you in this issue (that you may not were aware of) since you worked on something similar in #9472

[benjaoming]

Great find @humitos ! We really have an issue for everything in this backlog :)

Since a Build Troubleshooting page now exists and has a "Git errors" section, it could be natural to add additional sections for other types of build errors.

It was quite easy for me to write this section while working on a support case, recommending others with on-going troubleshooting to write it down and amend to this section 👍