readthedocs · tapaswenipathak · Aug 24, 2019 · Aug 24, 2019 · Aug 24, 2019 · Aug 27, 2019
diff --git a/docs/.tx/config b/docs/.tx/config
@@ -325,19 +325,19 @@ source_file = _build/locale/guides/index.pot
 source_lang = en
 type = PO
 
-[readthedocs-docs.guides--build-notifications]
+[readthedocs-docs.guides--how-to--build-notifications]
 file_filter = locale/<lang>/LC_MESSAGES/guides/build-notifications.po
 source_file = _build/locale/guides/build-notifications.pot
 source_lang = en
 type = PO
 
-[readthedocs-docs.guides--adding-custom-css]
+[readthedocs-docs.guides--how-to--adding-custom-css]
 file_filter = locale/<lang>/LC_MESSAGES/guides/adding-custom-css.po
 source_file = _build/locale/guides/adding-custom-css.pot
 source_lang = en
 type = PO
 
-[readthedocs-docs.guides--manage-translations]
+[readthedocs-docs.guides--how-to--manage-translations]
 file_filter = locale/<lang>/LC_MESSAGES/guides/manage-translations.po
 source_file = _build/locale/guides/manage-translations.pot
 source_lang = en
@@ -349,7 +349,7 @@ source_file = _build/locale/guides/wipe-environment.pot
 source_lang = en
 type = PO
 
-[readthedocs-docs.guides--remove-edit-buttons]
+[readthedocs-docs.guides--troubleshooting--remove-edit-buttons]
 file_filter = locale/<lang>/LC_MESSAGES/guides/remove-edit-buttons.po
 source_file = _build/locale/guides/remove-edit-buttons.pot
 source_lang = en

diff --git a/.../guides/github-build-status-reporting.gif → .../how-to/github-build-status-reporting.gif b/.../guides/github-build-status-reporting.gif → .../how-to/github-build-status-reporting.gif
diff --git a/...s/guides/google-search-engine-results.png → ...s/how-to/google-search-engine-results.png b/...s/guides/google-search-engine-results.png → ...s/how-to/google-search-engine-results.png
diff --git a/docs/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst
@@ -113,7 +113,7 @@ our own goals.
 
 We have taken steps to address some of the privacy concerns surrounding GA.
 These steps apply both to analytics collected by Read the Docs and when
-:doc:`authors enable analytics on their docs </guides/google-analytics>`.
+:doc:`authors enable analytics on their docs </guides/how-to/google-analytics>`.
 
 * Users can opt-out of analytics by using the Do Not Track feature of their browser.
 * Read the Docs instructs Google to anonymize IP addresses sent to them.

diff --git a/docs/api/v3.rst b/docs/api/v3.rst
@@ -864,7 +864,7 @@ Environment Variables
 Environment Variables are variables that you can define for your project.
 These variables are used in the build process when building your documentation.
 They are useful to define secrets in a safe way that can be used by your documentation to build properly.
-See :doc:`/guides/environment-variables`
+See :doc:`/guides/troubleshooting/environment-variables`
 
 
 Environment Variable details

diff --git a/docs/builds.rst b/docs/builds.rst
@@ -61,7 +61,7 @@ Read the Docs cannot create a PDF version of your documentation with the *Mkdocs
 
 .. warning::
 
-   We strongly recommend to :ref:`pin the MkDocs version <guides/specifying-dependencies:Specifying Dependencies>`
+   We strongly recommend to :ref:`pin the MkDocs version <guides/troubleshooting/specifying-dependencies:Specifying Dependencies>`
    used for your project to build the docs to avoid potential future incompatibilities.
 
 
@@ -109,7 +109,7 @@ An example in code:
     Regardless of whether you build your docs with Sphinx or MkDocs,
     we recommend you pin the version of Sphinx or Mkdocs you want us to use.
     You can do this the same way other
-    :doc:`dependencies are specified <guides/specifying-dependencies>`.
+    :doc:`dependencies are specified <guides/troubleshooting/specifying-dependencies>`.
     Some examples of pinning versions might be ``sphinx<2.0`` or ``mkdocs>=1.0``.
 
 Builder responsibility
@@ -172,8 +172,6 @@ If you're having trouble getting your version to build, try wiping out the exist
 Build environment
 -----------------
 
-The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment variables when building your documentation:
-
 .. csv-table::
    :header-rows: 1
 
@@ -187,4 +185,4 @@ The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment va
 
    In case extra environment variables are needed to the build process (like secrets, tokens, etc),
    you can add them going to :guilabel:`Admin` > :guilabel:`Environment Variables` in your project.
-   See :doc:`guides/environment-variables`.
+   See :doc:`guides/troubleshooting/environment-variables`.
diff --git a/docs/custom_installs/customization.rst b/docs/custom_installs/customization.rst
@@ -1,4 +1,4 @@
-Customizing your install
+Customizing Your Install
 ========================
 
 Read the Docs has a lot of :doc:`/development/settings` that help customize your install.

diff --git a/docs/custom_installs/index.rst b/docs/custom_installs/index.rst
@@ -1,4 +1,4 @@
-Info about custom installs
+Info About Custom Installs
 ==========================
 
 Read the Docs is open source, which means you can run your own version of it.

diff --git a/docs/development/issue-labels.rst b/docs/development/issue-labels.rst
@@ -1,4 +1,4 @@
-Overview of issue labels
+Overview of Issue Labels
 ========================
 
 Here is a full list of labels that we use in the `GitHub issue tracker`_ and

diff --git a/docs/development/symlinks.rst b/docs/development/symlinks.rst
@@ -1,4 +1,4 @@
-How we use symlinks
+How We Use Symlinks
 ===================
 
 Read the Docs stays highly available by serving all documentation pages out of nginx.

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -75,7 +75,7 @@ My project requires different settings than those available under Admin
 Read the Docs offers some settings which can be used for a variety of purposes,
 such as to use the latest version of sphinx or pip. To enable these settings,
 please send an email to [email protected] and we will change the settings for the project.
-Read more about these settings :doc:`here <guides/feature-flags>`.
+Read more about these settings :doc:`here <guides/troubleshooting/feature-flags>`.
 
 I get import errors on libraries that depend on C modules
 ---------------------------------------------------------
@@ -116,7 +116,7 @@ following settings::
 Deleting a stale or broken build environment
 --------------------------------------------
 
-See :doc:`guides/wipe-environment`.
+See :doc:`guides/troubleshooting/wipe-environment`.
 
 How do I host multiple projects on one custom domain?
 -----------------------------------------------------
@@ -194,7 +194,7 @@ and as a result, it tends to look a bit better with the default theme.
 .. note::
 
    To use these extensions you need to specify the dependencies on your project
-   by following this :doc:`guide <guides/specifying-dependencies>`.
+   by following this :doc:`guide <guides/troubleshooting/specifying-dependencies>`.
 
 Can I document a python package that is not at the root of my repository?
 -------------------------------------------------------------------------

diff --git a/docs/features.rst b/docs/features.rst
@@ -8,7 +8,7 @@ GitHub, Bitbucket and GitLab Integration
 
 We now support linking by default in the sidebar. It links to the page on your host, which should help people quickly update typos and send pull requests to contribute to project documentation.
 
-More information can be found in :doc:`guides/vcs`.
+More information can be found in :doc:`guides/troubleshooting/vcs`.
 
 Auto-updating
 -------------
@@ -26,7 +26,7 @@ Canonical URLs
 
 Canonical URLs give your docs better search performance, by pointing all URLs to one version. This also helps to solve the issues around users landing on outdated versions of documentation.
 
-More information can be found in the :doc:`guides/canonical` page.
+More information can be found in the :doc:`guides/troubleshooting/canonical` page.
 
 Versions
 --------

diff --git a/docs/guides/adding-custom-css.rst → docs/guides/how-to/adding-custom-css.rst b/docs/guides/adding-custom-css.rst → docs/guides/how-to/adding-custom-css.rst
diff --git a/...ides/autobuild-docs-for-pull-requests.rst → ...w-to/autobuild-docs-for-pull-requests.rst b/...ides/autobuild-docs-for-pull-requests.rst → ...w-to/autobuild-docs-for-pull-requests.rst
@@ -2,7 +2,7 @@ Autobuild Documentation for Pull Requests
 =========================================
 
 Read the Docs allows autobuilding documentation for pull/merge requests for GitHub or GitLab projects.
-This feature is currently available under a :doc:`Feature Flag </guides/feature-flags>`.
+This feature is currently available under a :doc:`Feature Flag </guides/troubleshooting/feature-flags>`.
 So, you can enable this feature by sending us an `email <mailto:[email protected]>`__ including your project URL.
 
 Features
@@ -21,11 +21,11 @@ Features
   and after the build has finished we send success notification if the build succeeded without any error
   or failure notification if the build failed.
 
-.. figure:: ../_static/images/guides/github-build-status-reporting.gif
+.. figure:: ../../_static/images/guides/how-to/github-build-status-reporting.gif
     :align: center
     :alt: GitHub Build Status Reporting for Pull Requests.
     :figwidth: 80%
-    :target: ../_static/images/guides/github-build-status-reporting.gif
+    :target: ../../_static/images/guides/how-to/github-build-status-reporting.gif
 
     GitHub Build Status Reporting for Pull Requests
 

diff --git a/docs/guides/build-notifications.rst → docs/guides/how-to/build-notifications.rst b/docs/guides/build-notifications.rst → docs/guides/how-to/build-notifications.rst
diff --git a/...guides/build-using-too-many-resources.rst → ...how-to/build-using-too-many-resources.rst b/...guides/build-using-too-many-resources.rst → ...how-to/build-using-too-many-resources.rst
diff --git a/docs/guides/google-analytics.rst → docs/guides/how-to/google-analytics.rst b/docs/guides/google-analytics.rst → docs/guides/how-to/google-analytics.rst
diff --git a/docs/guides/index.rst → docs/guides/how-to/index.rst b/docs/guides/index.rst → docs/guides/how-to/index.rst
@@ -16,13 +16,11 @@ whether that is Sphinx or MkDocs.
     :maxdepth: 1
 
     adding-custom-css
-    custom-404-page
     manage-translations
-    mkdocs-old-versions
-    pdf-non-ascii-languages
     remove-edit-buttons
-    vcs
-
+    build-notifications
+    build-using-too-many-resources
+    technical-docs-seo-guide
 
 Read the Docs how-to guides
 ---------------------------
@@ -34,14 +32,5 @@ These guides will help you customize or tune aspects of the Read the Docs build
 
     autobuild-docs-for-pull-requests
     build-notifications
-    build-using-too-many-resources
     technical-docs-seo-guide
-    canonical
-    conda
-    environment-variables
-    feature-flags
     google-analytics
-    searching-with-readthedocs
-    sitemaps
-    specifying-dependencies
-    wipe-environment
diff --git a/docs/guides/manage-translations.rst → docs/guides/how-to/manage-translations.rst b/docs/guides/manage-translations.rst → docs/guides/how-to/manage-translations.rst
diff --git a/docs/guides/remove-edit-buttons.rst → docs/guides/how-to/remove-edit-buttons.rst b/docs/guides/remove-edit-buttons.rst → docs/guides/how-to/remove-edit-buttons.rst
diff --git a/docs/guides/technical-docs-seo-guide.rst → ...uides/how-to/technical-docs-seo-guide.rst b/docs/guides/technical-docs-seo-guide.rst → ...uides/how-to/technical-docs-seo-guide.rst
@@ -19,7 +19,7 @@ that is answerable by your documentation, that your docs appear in the results.*
 This guide isn't meant to be your only resource on SEO,
 and there's a lot of SEO topics not covered here.
 For additional reading, please see the
-:ref:`external resources <guides/technical-docs-seo-guide:External resources>` section.
+:ref:`external resources <guides/how-to/technical-docs-seo-guide:External resources>` section.
 
 While many of the topics here apply to all forms of technical documentation,
 this guide will focus on Sphinx, which is the most common
@@ -86,8 +86,8 @@ Optimizing your docs for search engine spiders
 Once a crawler or spider finds your site, it will follow links and redirects
 in an attempt to find any and all pages on your site.
 While there are a few ways to guide the search engine in its crawl
-for example by using a :ref:`sitemap <guides/technical-docs-seo-guide:Use a sitemap.xml file>`
-or a :ref:`robots.txt file <guides/technical-docs-seo-guide:Use a robots.txt file>`
+for example by using a :ref:`sitemap <guides/how-to/technical-docs-seo-guide:Use a sitemap.xml file>`
+or a :ref:`robots.txt file <guides/how-to/technical-docs-seo-guide:Use a robots.txt file>`
 which we'll discuss shortly,
 the most important thing is making sure the spider can follow links on your site
 and get to all your pages.
@@ -141,7 +141,7 @@ Redirects
 ~~~~~~~~~
 
 Redirects tell search engines when content has moved.
-For example, if this guide moved from ``guides/technical-docs-seo-guide.html`` to ``guides/sphinx-seo-guide.html``,
+For example, if this guide moved from ``guides/how-to/technical-docs-seo-guide.html`` to ``guides/sphinx-seo-guide.html``,
 there will be a time period where search engines will still have the old URL in their index
 and will still be showing it to users.
 This is why it is important to update your own links within your docs as well as redirecting.
@@ -161,7 +161,7 @@ The canonical URL tells search engines where the original version
 your documentation is even if you have multiple versions on the internet
 (for example, incomplete translations or deprecated versions).
 
-Read the Docs supports :doc:`setting the canonical URL </guides/canonical>`
+Read the Docs supports :doc:`setting the canonical URL </guides/troubleshooting/canonical>`
 if you are using a :doc:`custom domain </custom_domains>`
 under :guilabel:`Admin` > :guilabel:`Domains`
 in the Read the Docs dashboard.
@@ -197,7 +197,7 @@ or any alternate language versions of a page.
 
 Read the Docs generates a sitemap for you that contains the last time
 your documentation was updated as well as links to active versions, subprojects, and translations your project has.
-We have a small separate guide on :doc:`sitemaps </guides/sitemaps>`.
+We have a small separate guide on :doc:`sitemaps </guides/troubleshooting/sitemaps>`.
 
 See the `Google docs on building a sitemap <https://support.google.com/webmasters/answer/183668>`_.
 
@@ -219,10 +219,10 @@ In Sphinx, you can customize your meta description using the following Restructu
             can let you customize the look and feel of your docs or add additional functionality.
 
 
-.. figure:: ../_static/images/guides/google-search-engine-results.png
+.. figure:: ../../_static/images/guides/how-to/google-search-engine-results.png
     :align: center
     :figwidth: 80%
-    :target: ../_static/images/guides/google-search-engine-results.png
+    :target: ../../_static/images/guides/how-to/google-search-engine-results.png
 
     Google search engine results showing a customized meta description
 
@@ -257,7 +257,7 @@ Some of the most valuable feedback these provide include:
 * Google and Bing will show pages that were previously indexed that now give a 404
   (or more rarely a 500 or other status code).
   These will remain in the index for some time but will eventually be removed.
-  This is a good opportunity to create a :ref:`redirect <guides/technical-docs-seo-guide:Redirects>`.
+  This is a good opportunity to create a :ref:`redirect <guides/how-to/technical-docs-seo-guide:Redirects>`.
 * These tools will show any crawl issues with your documentation.
 * Search Console and Webmaster Tools will highlight security issues found
   or if Google or Bing took action against your site because they believe it is spammy.
@@ -266,7 +266,7 @@ Some of the most valuable feedback these provide include:
 Analytics tools
 ~~~~~~~~~~~~~~~
 
-A tool like :doc:`Google Analytics </guides/google-analytics>`
+A tool like :doc:`Google Analytics </guides/how-to/google-analytics>`
 can give you feedback about the search terms people use to find your docs,
 your most popular pages, and lots of other useful data.
 

diff --git a/docs/guides/canonical.rst → docs/guides/troubleshooting/canonical.rst b/docs/guides/canonical.rst → docs/guides/troubleshooting/canonical.rst
diff --git a/docs/guides/conda.rst → docs/guides/troubleshooting/conda.rst b/docs/guides/conda.rst → docs/guides/troubleshooting/conda.rst
@@ -11,7 +11,7 @@ This work was funded by `Clinical Graphics`_ -- many thanks for their support of
 Activating Conda
 ----------------
 
-Conda support is available using a :doc:`../config-file/index`, see :ref:`config-file/v2:conda`.
+Conda support is available using a :doc:`../../config-file/index`, see :ref:`config-file/v2:conda`.
 
 This Conda environment will also have Sphinx and other build time dependencies installed.
 It will use the same order of operations that we support currently:

diff --git a/docs/guides/custom-404-page.rst → ...uides/troubleshooting/custom-404-page.rst b/docs/guides/custom-404-page.rst → ...uides/troubleshooting/custom-404-page.rst
diff --git a/docs/guides/environment-variables.rst → ...troubleshooting/environment-variables.rst b/docs/guides/environment-variables.rst → ...troubleshooting/environment-variables.rst
diff --git a/docs/guides/feature-flags.rst → .../guides/troubleshooting/feature-flags.rst b/docs/guides/feature-flags.rst → .../guides/troubleshooting/feature-flags.rst
diff --git a/docs/guides/troubleshooting/index.rst b/docs/guides/troubleshooting/index.rst
@@ -0,0 +1,38 @@
+Troubleshooting Guides
+======================
+
+These guides will help walk you through troubleshooting steps
+related to Read the Docs itself, documentation tools like Sphinx and MkDocs
+and how to write successful documentation.
+
+
+Sphinx & MkDocs troubleshooting guides
+--------------------------------------
+
+These are the troubleshooting guides for your documentation authoring tool
+whether that is Sphinx or MkDocs.
+
+.. toctree::
+    :maxdepth: 1
+
+    custom-404-page
+    mkdocs-old-versions
+    pdf-non-ascii-languages
+    vcs
+    feature-flags
+    sitemaps
+    wipe-environment
+
+Read the Docs troubleshooting guides
+-------------------------------------
+
+These troubleshooting guides are for the Read the Docs build environment.
+
+.. toctree::
+    :maxdepth: 1
+
+    canonical
+    conda
+    environment-variables
+    specifying-dependencies
+    searching-with-readthedocs
diff --git a/docs/guides/mkdocs-old-versions.rst → ...s/troubleshooting/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst → ...s/troubleshooting/mkdocs-old-versions.rst
@@ -29,7 +29,7 @@ To make your project continue using this version you will need to create a ``req
      markdown>=2.3.1,<2.5
 
 
-More detailed information about how to specify dependencies can be found :ref:`here <guides/specifying-dependencies:Specifying Dependencies>`.
+More detailed information about how to specify dependencies can be found :ref:`here <guides/troubleshooting/specifying-dependencies:Specifying Dependencies>`.
 
 
 Upgrade your custom theme to be compatible with later MkDocs versions

diff --git a/docs/guides/pdf-non-ascii-languages.rst → ...oubleshooting/pdf-non-ascii-languages.rst b/docs/guides/pdf-non-ascii-languages.rst → ...oubleshooting/pdf-non-ascii-languages.rst
diff --git a/docs/guides/searching-with-readthedocs.rst → ...leshooting/searching-with-readthedocs.rst b/docs/guides/searching-with-readthedocs.rst → ...leshooting/searching-with-readthedocs.rst
@@ -7,7 +7,7 @@ how to use advanced query syntax to get more accurate results and
 many other search features that Read the Docs supports with example searches.
 
 You can find information on the search architecture and how we index document on our
-:doc:`Search <../development/search>` docs.
+:doc:`Search <../../development/search>` docs.
 
 
 .. contents:: Table of contents
@@ -67,7 +67,7 @@ You can see these analytics in your project admin dashboard.
 .. note::
 
     Currently, this feature is in beta state and is available under a
-    :ref:`feature flag <guides/feature-flags:Available Flags>`.
+    :ref:`feature flag <guides/troubleshooting/feature-flags:Available Flags>`.
     We plan to make this available for everyone soon.
     If you want to test this feature out and help giving us feedback,
     please contact us via `GitHub issues`_.
@@ -102,7 +102,7 @@ Search inside subprojects
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We allow projects to configured as subprojects of another project.
-You can read more about this in our :doc:`Subprojects <../subprojects>` documentation.
+You can read more about this in our :doc:`Subprojects <../../subprojects>` documentation.
 
 If a search is made in a project which have one or more subprojects under it,
 the search results then also includes the results from subprojects because

diff --git a/docs/guides/sitemaps.rst → docs/guides/troubleshooting/sitemaps.rst b/docs/guides/sitemaps.rst → docs/guides/troubleshooting/sitemaps.rst
diff --git a/docs/guides/specifying-dependencies.rst → ...oubleshooting/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst → ...oubleshooting/specifying-dependencies.rst
diff --git a/docs/guides/vcs.rst → docs/guides/troubleshooting/vcs.rst b/docs/guides/vcs.rst → docs/guides/troubleshooting/vcs.rst
diff --git a/docs/guides/wipe-environment.rst → ...ides/troubleshooting/wipe-environment.rst b/docs/guides/wipe-environment.rst → ...ides/troubleshooting/wipe-environment.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -122,7 +122,8 @@ out of your documentation and Read the Docs.
   :doc:`Automatic redirects <automatic-redirects>`
 
 * **Topic specific guides**:
-  :doc:`How-to guides <guides/index>`
+  :doc:`How-to guides <guides/how-to/index>`
+  :doc:`Troubleshooting guides <guides/troubleshooting/index>`
 
 * **Extending Read the Docs**:
   :doc:`REST API <api/index>`
@@ -142,7 +143,8 @@ out of your documentation and Read the Docs.
    user-defined-redirects
    automatic-redirects
 
-   guides/index
+   guides/how-to/index
+   guides/troubleshooting/index
 
    api/index
 

diff --git a/docs/locale/da/LC_MESSAGES/faq.po b/docs/locale/da/LC_MESSAGES/faq.po
@@ -180,7 +180,7 @@ msgid "Deleting a stale or broken build environment"
 msgstr ""
 
 #: ../../faq.rst:113
-msgid "See :doc:`guides/wipe-environment`."
+msgid "See :doc:`guides/troubleshooting/wipe-environment`."
 msgstr ""
 
 #: ../../faq.rst:116