readthedocs · astrojuanlu · Sep 28, 2021 · Sep 27, 2021 · Sep 27, 2021 · Sep 27, 2021
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/guides/build-notifications.rst → docs/build-notifications.rst b/docs/guides/build-notifications.rst → docs/build-notifications.rst
diff --git a/docs/guides/canonical.rst → docs/canonical.rst b/docs/guides/canonical.rst → docs/canonical.rst
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 [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 <feature-flags>`.
 
 
 I get import errors on libraries that depend on C modules

diff --git a/docs/guides/feature-flags.rst → docs/feature-flags.rst b/docs/guides/feature-flags.rst → docs/feature-flags.rst
diff --git a/docs/guides/google-analytics.rst → docs/google-analytics.rst b/docs/guides/google-analytics.rst → docs/google-analytics.rst
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/guides/vcs.rst b/docs/guides/vcs.rst
@@ -1,5 +1,5 @@
-Version Control System Integration
-==================================
+Version Control System integration on your Sphinx theme
+=======================================================
 
 .. note::
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -77,12 +77,15 @@ and some of the core features of Read the Docs.
 * **Overview of core features**:
   :doc:`Incoming webhooks </webhooks>` |
   :doc:`/custom_domains` |
+  :doc:`/canonical` |
   :doc:`/versions` |
   :doc:`/downloadable-documentation` |
   :doc:`/hosting` |
   :doc:`/server-side-search` |
-  :doc:`/analytics`
-  :doc:`/pull-requests`
+  :doc:`/analytics` |
+  :doc:`/google-analytics` |
+  :doc:`/pull-requests` |
+  :doc:`/build-notifications`
 
 * **Connecting with GitHub, BitBucket, or GitLab**:
   :doc:`Connecting your VCS account </connected-accounts>` |
@@ -106,12 +109,15 @@ and some of the core features of Read the Docs.
    /config-file/index
    /webhooks
    /custom_domains
+   /canonical
    /versions
    /downloadable-documentation
    /hosting
    /server-side-search
    /analytics
+   /google-analytics
    /pull-requests
+   /build-notifications
 
    /connected-accounts
 
@@ -123,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
 ----------------------------------
@@ -152,7 +175,8 @@ out of your documentation and Read the Docs.
 
 * **Advanced project configuration**:
   :doc:`subprojects` |
-  :doc:`Single version docs <single_version>`
+  :doc:`Single version docs <single_version>` |
+  :doc:`feature-flags`
 
 * **Multi-language documentation**:
   :doc:`Translations and localization <localization>`
@@ -180,6 +204,7 @@ out of your documentation and Read the Docs.
 
    subprojects
    single_version
+   feature-flags
 
    localization
 

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/