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.