From 4af88137f93f7a63d5c87912e3f5d7a7dff7736f Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Fri, 27 Jan 2023 20:24:16 +0100 Subject: [PATCH] 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 <25510+ericholscher@users.noreply.github.com> * Reuse contribution :tip: box, addresse @ericholscher comments --------- Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/user/faq.rst | 2 +- docs/user/{ => guides}/build-troubleshooting.rst | 8 +++----- .../guides/build-using-too-many-resources.rst | 15 +++++++++------ docs/user/guides/troubleshooting/index.rst | 14 ++++++++++++++ docs/user/index.rst | 2 +- .../user/shared/contribute_to_troubleshooting.rst | 5 +++++ 6 files changed, 33 insertions(+), 13 deletions(-) rename docs/user/{ => guides}/build-troubleshooting.rst (94%) create mode 100644 docs/user/guides/troubleshooting/index.rst create mode 100644 docs/user/shared/contribute_to_troubleshooting.rst diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 27a27f3bafd..f74ca7c6ed1 100644 --- 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 b/docs/user/guides/build-troubleshooting.rst similarity index 94% rename from docs/user/build-troubleshooting.rst rename to docs/user/guides/build-troubleshooting.rst index 0235faa118a..d5ef1f74dab 100644 --- a/docs/user/build-troubleshooting.rst +++ b/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///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 index 2c18c24c8b8..eab08f2b9f4 100644 --- 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 `. + +.. 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 new file mode 100644 index 00000000000..452156bc43f --- /dev/null +++ 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 index 1fc33f31302..f16e19b4710 100644 --- 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 /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 new file mode 100644 index 00000000000..d993b2d1b81 --- /dev/null +++ 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 support@readthedocs.org + or contribute directly by clicking :guilabel:`Edit on GitHub` in the top right corner of this page.