Docs: Add new section "How-to / Troubleshooting" and move 2 existing …

…troubleshooting pages (#9914) * Relabel Build Troubleshooting as how-to and update introduction to a tip admonition * Add new level "how-to guides / troubleshooting" with 2 troubleshooting themes * Fix up introduction to slow builds troubleshooting * Add a tip box for the build issues page as well, slightly rephrased * Add suggestion for "Edit on GitHub" * refinement to "terminated by Read the Docs" * replace spoken word with written word * Apply suggestions from code review Co-authored-by: Eric Holscher <[email protected]> * Reuse contribution :tip: box, addresse @ericholscher comments --------- Co-authored-by: Eric Holscher <[email protected]>
readthedocs · Jan 27, 2023 · 4af8813 · 4af8813
1 parent bd0bbe2
commit 4af8813
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 13 deletions.
diff --git a/docs/user/faq.rst b/docs/user/faq.rst
@@ -34,7 +34,7 @@ you can use an important word or message from the error to search for a solution
 
 .. seealso::
 
-   :doc:`/build-troubleshooting`
+   :doc:`/guides/build-troubleshooting`
       Common errors and solutions for build failures.
 
    Other FAQ entries

diff --git a/docs/user/build-troubleshooting.rst → docs/user/guides/build-troubleshooting.rst b/docs/user/build-troubleshooting.rst → docs/user/guides/build-troubleshooting.rst
@@ -1,8 +1,7 @@
-Build troubleshooting
-=====================
+Troubleshooting build errors
+============================
 
-This section is very specific and may change over time.
-Please help us keep it updated and contribute your own build errors and resolutions.
+.. include:: /shared/contribute_to_troubleshooting.rst
 
 
 Git errors
@@ -60,7 +59,6 @@ Permission denied (publickey)
    - ``https://bitbucket.org/<username>/<repo>/admin/access-keys/``
 
 
-
 ERROR: Repository not found.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/user/guides/build-using-too-many-resources.rst b/docs/user/guides/build-using-too-many-resources.rst
@@ -1,11 +1,14 @@
-My Build is Using Too Many Resources
-====================================
+Troubleshooting slow builds
+===========================
 
-We limit build resources to make sure that users don't overwhelm our build systems.
-If you are running into this issue,
-there are a couple fixes that you might try.
+In case you are waiting a long time for your builds to finish
+or your builds are terminated by exceeding general resource limits,
+this troubleshooting guide will help you resolve some of the most common issues causing slow builds.
 
-.. note:: The current build limits can be found on our :doc:`/builds` page.
+Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems.
+The current build limits can be found on our :ref:`Build resources reference <builds:Build resources>`.
+
+.. include:: /shared/contribute_to_troubleshooting.rst
 
 Reduce formats you're building
 ------------------------------

diff --git a/docs/user/guides/troubleshooting/index.rst b/docs/user/guides/troubleshooting/index.rst
@@ -0,0 +1,14 @@
+Troubleshooting guides
+----------------------
+
+In the following guides,
+you can learn how to fix common problems using Read the Docs.
+
+.. File locations are a bit odd here because of legacy.
+.. We will move files to new locations and create redirects in a later refactor
+
+.. toctree::
+   :maxdepth: 1
+
+   Build errors <../build-troubleshooting>
+   Slow builds <../build-using-too-many-resources>
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -96,6 +96,7 @@ to help you create fantastic documentation for your project.
    /guides/authors
    /guides/administrators
    /guides/developers
+   Troubleshooting </guides/troubleshooting/index>
    /examples
    /faq
 
@@ -159,7 +160,6 @@ and some of the core features of Read the Docs.
 
    /builds
    /build-customization
-   /build-troubleshooting
    /environment-variables
 
    /support

diff --git a/docs/user/shared/contribute_to_troubleshooting.rst b/docs/user/shared/contribute_to_troubleshooting.rst
@@ -0,0 +1,5 @@
+.. tip::
+
+   Please help us keep this section updated and contribute your own error resolutions, performance improvements, etc.
+   Send in your helpful comments or ideas 💡 to [email protected]
+   or contribute directly by clicking :guilabel:`Edit on GitHub` in the top right corner of this page.