readthedocs/readthedocs.org

Add user doc on what to do on common build failures

Open

#4,729 建立於 2018年10月4日

在 GitHub 查看
 (9 留言) (3 反應) (0 負責人)Python (7,765 star) (3,748 fork)batch import
AcceptedGood First IssueNeeded: documentation

描述

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.

貢獻者指南

技術棧
python
領域
documentation
議題類型
documentation
難度面向新貢獻者的預計實作難度，1 表示很小改動，5 表示專家級工作。
2
預計時間有經驗貢獻者完成調查、實作、測試並準備 pull request 的粗略時間範圍。
1-3 hours
活動狀態議題目前的可參與程度：新鮮、活躍、陳舊、阻塞或等待維護者輸入。
stale
清晰度議題是否清楚說明預期改動、驗收標準和下一步。
clear
前置要求
無
新手友善度1-100 的估計分數，表示該議題對首次貢獻者的友善程度。
70
研究方向
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.
Add user doc on what to do on common build failures · readthedocs/readthedocs.org#4729 | Good First Issue