Restructure guides

astrojuanlu · astrojuanlu · commit a84eb3c5fc57 · 2021-09-27T16:42:04.000+02:00
Close #8321.
diff --git a/docs/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst
@@ -119,13 +119,13 @@ 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 </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.
 * The cookies set by GA expire in 30 days rather than the default 2 years.
 * Project maintainers can completely disable analytics on their own projects.
-  Follow the steps in :ref:`guides/google-analytics:Disabling Google Analytics on your project`.
+  Follow the steps in :ref:`google-analytics:Disabling Google Analytics on your project`.
 
 
 Why we use analytics
diff --git a/docs/analytics.rst b/docs/analytics.rst
@@ -21,4 +21,4 @@ You can also access to analytics data from :ref:`search results <server-side-sea
 .. note::
 
    If you require more information about page views,
-   you can use a solution like :doc:`Google Analytics </guides/google-analytics>`.
+   you can use a solution like :doc:`Google Analytics </google-analytics>`.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -50,7 +50,7 @@ see :ref:`faq:My documentation requires additional dependencies`.
 Read the Docs offers some settings which can be used for a variety of purposes.
 To enable these settings,
 please send an email to support@readthedocs.org 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 <feature-flags>`.
 
 
 I get import errors on libraries that depend on C modules
diff --git a/docs/guides/administrators.rst b/docs/guides/administrators.rst
@@ -0,0 +1,22 @@
+Guides for project administrators
+---------------------------------
+
+These guides cover common use cases
+relevant for managing documentation projects,
+using the Read the Docs web interface
+and making changes to the configuration files.
+
+For an introduction to Read the Docs,
+have a look at our :doc:`/tutorial/index`.
+
+.. toctree::
+   :maxdepth: 1
+
+   technical-docs-seo-guide
+   manage-translations
+   searching-with-readthedocs
+   hiding-a-version
+   deprecating-content
+   pdf-non-ascii-languages
+   importing-private-repositories
+   wipe-environment
diff --git a/docs/guides/authors.rst b/docs/guides/authors.rst
@@ -0,0 +1,18 @@
+Guides for documentation authors
+--------------------------------
+
+These guides offer some tips and tricks to author documentation
+with the tools supported on Read the Docs.
+Only reStructuredText or Markdown knowledge
+and minimal configuration tweaking are needed.
+
+For an introduction to Sphinx and Mkdocs,
+have a look at our :doc:`/intro/getting-started-with-sphinx`
+and :doc:`/intro/getting-started-with-mkdocs`.
+
+.. toctree::
+   :maxdepth: 1
+
+   cross-referencing-with-sphinx
+   intersphinx
+   jupyter
diff --git a/docs/guides/commercial.rst b/docs/guides/commercial.rst
diff --git a/docs/guides/conda.rst b/docs/guides/conda.rst
@@ -62,7 +62,7 @@ so they can have any value, or not be present at all.
 .. warning:: Pinning Sphinx and other Read the Docs core dependencies
    is not yet supported by default when using conda (see `this GitHub issue for discussion`_).
    If your project needs it, request that we enable the ``CONDA_APPEND_CORE_REQUIREMENTS``
-   :ref:`feature flag <guides/feature-flags:Feature Flags>`.
+   :ref:`feature flag <feature-flags:Feature Flags>`.
 
 .. _this GitHub issue for discussion: https://github.com/readthedocs/readthedocs.org/issues/3829
 .. _exporting a conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#sharing-an-environment
@@ -178,7 +178,7 @@ minimize the running time or the memory usage:
   and opting out of the defaults adding ``nodefaults``.
 - Constrain the package versions as much as possible to reduce the solution space.
 - Use mamba_, an alternative package manager fully compatible with conda packages,
-  by requesting the ``CONDA_USES_MAMBA`` :ref:`feature flag <guides/feature-flags:Feature Flags>`.
+  by requesting the ``CONDA_USES_MAMBA`` :ref:`feature flag <feature-flags:Feature Flags>`.
 - And, if all else fails,
   :ref:`request more resources <guides/build-using-too-many-resources:Requests more resources>`.
 
diff --git a/docs/guides/developers.rst b/docs/guides/developers.rst
@@ -0,0 +1,19 @@
+Guides for developers and designers
+-----------------------------------
+
+These guides are helpful for developers and designers
+seeking to extend the authoring tools
+or customize the documentation appearance.
+
+.. toctree::
+   :maxdepth: 1
+
+   private-python-packages
+   private-submodules
+   adding-custom-css
+   reproducible-builds
+   embedding-content
+   conda
+   remove-edit-buttons
+   build-using-too-many-resources
+   vcs
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -11,6 +11,6 @@ and how to write successful documentation.
 .. toctree::
    :maxdepth: 2
 
-   tools
-   platform
-   commercial
+   authors
+   administrators
+   developers
diff --git a/docs/guides/platform.rst b/docs/guides/platform.rst
diff --git a/docs/guides/technical-docs-seo-guide.rst b/docs/guides/technical-docs-seo-guide.rst
@@ -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 </canonical>`
 if you are using a :doc:`custom domain </custom_domains>`
 under :guilabel:`Admin` > :guilabel:`Domains`
 in the Read the Docs dashboard.
@@ -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 </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/tools.rst b/docs/guides/tools.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -129,25 +129,42 @@ and some of the core features of Read the Docs.
    /faq
 
 
-Step-by-step Guides
--------------------
+How-to Guides
+-------------
 
 These guides will help walk you through specific use cases
 related to Read the Docs itself, documentation tools like Sphinx and MkDocs
 and how to write successful documentation.
 
-* :doc:`/guides/tools`
-* :doc:`/guides/platform`
-* :doc:`/guides/commercial`
+* **For documentation authors**:
+  :doc:`/guides/cross-referencing-with-sphinx` |
+  :doc:`/guides/intersphinx` |
+  :doc:`/guides/jupyter` |
+  :doc:`Other guides for authors </guides/authors>`
+
+* **For project administrators**:
+  :doc:`/guides/technical-docs-seo-guide` |
+  :doc:`/guides/manage-translations` |
+  :doc:`/guides/searching-with-readthedocs` |
+  :doc:`/guides/private-submodules` |
+  :doc:`Other guides for administrators </guides/administrators>`
+
+* **For developers and designers**:
+  :doc:`/guides/private-python-packages` |
+  :doc:`/guides/adding-custom-css` |
+  :doc:`/guides/reproducible-builds` |
+  :doc:`/guides/embedding-content` |
+  :doc:`/guides/conda` |
+  :doc:`Other guides for developers and designers </guides/developers>`
 
 .. toctree::
  :maxdepth: 2
  :hidden:
- :caption: Step-by-step Guides
+ :caption: How-to Guides
 
- /guides/tools
- /guides/platform
- /guides/commercial
+ /guides/authors
+ /guides/administrators
+ /guides/developers
 
 Advanced features of Read the Docs
 ----------------------------------
diff --git a/docs/single_version.rst b/docs/single_version.rst
@@ -23,6 +23,6 @@ if pip was set as a "Single Version" project, then links to its documentation wo
 ``http://pip.readthedocs.io/`` rather than the default ``http://pip.readthedocs.io/en/latest/``.
 
 Documentation at ``/<language>/<default_version>/`` will still be served for backwards compatibility reasons.
-However, our usage of :doc:`guides/canonical` should stop these from being indexed by Google.
+However, our usage of :doc:`canonical` should stop these from being indexed by Google.
 
 .. _dashboard: https://readthedocs.org/dashboard/
