Add user doc on what to do on common build failures · readthedocs/readthedocs.org#4729

(9 comments) (3 reactions) (0 assignees)Python (7,765 stars) (3,748 forks)batch import

AcceptedGood First IssueNeeded: documentation

Description

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 #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.

Tech stack: python
Domain: documentation
Issue type: documentation
Difficulty: 2
Estimated time: 1-3 hours
Activity status: stale
Clarity: clear
Prerequisites: None
Newbie friendliness: 70
Research direction: Examine the existing FAQ entry mentioned in the issue to understand the current content. Review the documentation structure to decide where to place the new page. Look at issue #5651 for context on the email workflow. Write the doc covering the three failure scenarios: timeouts/memory, general server errors, and configuration errors, linking to relevant schema docs.