Docs: Navigation reorder (Diátaxis) (#10026)

* Put the toctrees at the top of index.rst content

* Re-order explanation

* Move how-to guides before explanation

* Emojis in navigation

* re-order reference items

* Lots of TOC refactoring

* A bit more futzing

* Remove underscores from files, and do a bit more cleanup

* Fix links

* Single TOC for all

---------

Co-authored-by: Eric Holscher <[email protected]>

Author: benjaoming

docs/conf.py

@@ -61,6 +61,7 @@
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"
+intersphinx_cache_limit = 14  # cache for 2 weeks
 intersphinx_timeout = 3  # 3 seconds timeout
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.10/", None),

docs/user/about/index.rst

@@ -1,18 +1,6 @@
 About Read the Docs
 ===================
 
-.. toctree::
-   :hidden:
-
-   /commercial/index
-   /reference/policies
-   /advertising/index
-   /story
-   /sponsors
-   /open-source-philosophy
-   /team
-   /support
-
 Read the Docs is a C Corporation registered in Oregon.
 Our bootstrapped company is owned and fully controlled by the founders,
 and fully funded by our customers and advertisers.
@@ -38,9 +26,6 @@ This allows us to give back to the communities and projects that we support and
 We are proud about the way we manage our company and products,
 and are glad to have you on board with us in this :doc:`great documentation journey </story>`.
 
-Additional content
--------------------------------
-
 If you want to dive more into more specific information and our policies,
 we've brought most of the most important ones below.
 
@@ -68,7 +53,23 @@ we've brought most of the most important ones below.
 ⏩ :doc:`/support`
    Read this before asking for help: How to get support and where.
 
+⏩ :doc:`/glossary`
+   A useful index of terms used in our docs
+
 .. seealso::
 
    `Our website <https://about.readthedocs.com>`__
       Our primary website has general-purpose information about Read the Docs like pricing and feature overviews.
+
+.. toctree::
+   :hidden:
+
+   /commercial/index
+   /reference/policies
+   /advertising/index
+   /story
+   /sponsors
+   /open-source-philosophy
+   /team
+   /support
+   /glossary

docs/user/api/index.rst

@@ -12,3 +12,4 @@ from Read the Docs.
 
    v3
    v2
+   /server-side-search/api

docs/user/build-default-versions.rst

@@ -12,7 +12,7 @@ Default versions of dependencies
 
 Read the Docs supports two tools to build your documentation:
 `Sphinx <https://www.sphinx-doc.org/>`__ and `MkDocs <https://www.mkdocs.org/>`__.
-In order to provide :doc:`several features </features>`,
+In order to provide :doc:`several features </reference/features>`,
 Read the Docs injects or modifies some content while building your docs.
 
 In particular, if you don't specify the dependencies of your project,

docs/user/commercial/sharing.rst

@@ -1,5 +1,5 @@
-Sharing
-=======
+Private Documentation Sharing
+=============================
 
 .. include:: /shared/admonition-rtd-business.rst
 

docs/user/connected-accounts.rst

@@ -1,5 +1,5 @@
-Connecting your Git repository
-==============================
+How to connect your Git repository
+==================================
 
 In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
 automatically configures your Git repository and your Read the Docs project.

docs/user/features.rst

@@ -13,6 +13,7 @@ have a look at our :doc:`/tutorial/index`.
    :maxdepth: 1
 
    Connect your git repository <git-integrations>
+   /connected-accounts
    Connect your Read the Docs account to your Git repository <connecting-git-account>
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>

docs/user/guides/administrators.rst

@@ -16,6 +16,9 @@ and :doc:`/intro/getting-started-with-mkdocs`.
    cross-referencing-with-sphinx
    Link to external projects (Intersphinx) <intersphinx>
    jupyter
+   /guides/technical-docs-seo-guide
    Migrate from rST to MyST <migrate-rest-myst>
    enable-offline-formats
    Using search analytics <search-analytics>
+   /automatic-redirects
+   /science

docs/user/guides/authors.rst

@@ -1,7 +1,7 @@
 Troubleshooting build errors
 ============================
 
-.. include:: /shared/contribute_to_troubleshooting.rst
+.. include:: /shared/contribute-to-troubleshooting.rst
 
 
 Git errors

docs/user/guides/build-troubleshooting.rst

@@ -8,7 +8,7 @@ this troubleshooting guide will help you resolve some of the most common issues
 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 <builds:Build resources>`.
 
-.. include:: /shared/contribute_to_troubleshooting.rst
+.. include:: /shared/contribute-to-troubleshooting.rst
 
 Reduce formats you're building
 ------------------------------

docs/user/guides/build-using-too-many-resources.rst

@@ -15,7 +15,6 @@ or customize the documentation appearance.
    embedding-content
    conda
    remove-edit-buttons
-   build-using-too-many-resources
    edit-source-links-sphinx
    Setup Build Notifications <build-notifications>
    Use traffic analytics </analytics>

docs/user/guides/developers.rst

@@ -1,4 +1,4 @@
-:orphan: 
+:orphan:
 
 Guides
 ======
@@ -7,10 +7,10 @@ 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.
 
-
 .. toctree::
    :maxdepth: 2
 
    authors
    administrators
+   build-troubleshooting
    developers

docs/user/guides/index.rst

@@ -1,5 +1,5 @@
-Troubleshooting guides
-----------------------
+Guides for troubleshooting problems
+-----------------------------------
 
 In the following guides,
 you can learn how to fix common problems using Read the Docs.
@@ -10,5 +10,5 @@ you can learn how to fix common problems using Read the Docs.
 .. toctree::
    :maxdepth: 1
 
-   Build errors <../build-troubleshooting>
-   Slow builds <../build-using-too-many-resources>
+   ../build-troubleshooting
+   ../build-using-too-many-resources