Docs: Navigation reorder (Diátaxis)

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/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/guides/administrators.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/authors.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/troubleshooting/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.

docs/user/index.rst

@@ -10,18 +10,7 @@ Read the Docs: Documentation Simplified
    /intro/getting-started-with-sphinx
    /intro/getting-started-with-mkdocs
    /intro/import-guide
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: How-to guides 🪄
-
-   /guides/authors
-   /guides/administrators
-   /guides/developers
-   Troubleshooting </guides/troubleshooting/index>
    /examples
-   /faq
 
 .. toctree::
    :maxdepth: 2
@@ -30,32 +19,36 @@ Read the Docs: Documentation Simplified
 
    /choosing-a-site
    /integrations
-   /pull-requests
-   /science
-   /automatic-redirects
-   /guides/technical-docs-seo-guide
-   /localization
-   /build-notifications
-   /custom-domains
-   /connected-accounts
+   /builds
    /downloadable-documentation
-   /subprojects
-   /single_version
    /environment-variables
+   /subprojects
+   /localization
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: How-to guides 🪄
+
+   /guides/authors
+   /guides/administrators
+   /guides/developers
+   /guides/troubleshooting/index
 
 .. toctree::
    :maxdepth: 2
    :hidden:
    :caption: Reference 📚
 
    /reference/features
-   /about/index
-   /api/index
-   /server-side-search/api
+   /config-file/index
+   /build-customization
    /server-side-search/syntax
-   /reference/environment-variables
-   changelog
+   /faq
    /glossary
+   /api/index
+   /changelog
+   /about/index
    Developer Documentation 🔗 <https://dev.readthedocs.io>
 
 .. meta::
@@ -94,7 +87,7 @@ Open Source and User Focused |:heartbeat:|
 
 .. _Read the docs: https://readthedocs.org/
 
-You can find out more about our all the :doc:`/features` in these pages.
+You can find out more about our all the :doc:`features </reference/features>` in these pages.
 
 First steps
 -----------
@@ -121,7 +114,6 @@ Learn more about configuring your automated documentation builds
 and some of the core features of Read the Docs.
 
 * **Overview of core features**:
-  :doc:`/features` |
   :doc:`/custom-domains` |
   :doc:`/versions` |
   :doc:`/downloadable-documentation` |

docs/user/integrations.rst

@@ -6,7 +6,7 @@
        (Perhaps reuse this: https://about.readthedocs.com/images/homepage.png)
 
 
-Building documentation on every Git commit
+Integrations: building docs on each commit
 ==========================================
 
 Read the Docs is a *Continuous Documentation Deployment* platform for your software project.

docs/user/pull-requests.rst

@@ -2,9 +2,8 @@ Preview Documentation from Pull Requests
 ========================================
 
 Your project can be configured to build and host documentation for every new
-pull request. Previewing changes to your documentation during review makes it
-easier to catch documentation formatting and display issues introduced in pull
-requests.
+pull request. Previewing changes during review makes it
+easier to catch formatting and display issues before they go live.
 
 Features
 --------

docs/user/reference/features.rst

@@ -4,9 +4,6 @@ Feature reference
 
 .. TODO: Continue to add more features here.
 
-Hosting features
-----------------
-
 ⏩️ :doc:`/custom-domains`
   Documentation projects can use their own domain name.
   A project may define multiple domains,
@@ -20,38 +17,45 @@ Hosting features
   If you only have 1 version and translation,
   we also support :doc:`single version projects </single_version>` served at ``/``.
 
+⏩️ :doc:`/pull-requests`
+  Your project can be configured to build and host documentation for every new pull request.
+  Previewing changes during review makes it easier to catch formatting and display issues.
+
+⏩️ :doc:`/build-notifications`
+  Build notifications can alert you when your builds fail so you can take immediate action.
+
+⏩️ :doc:`/reference/analytics`
+  Traffic and Search analytics are built into the platform.
+  This allows you to easily see what the most popular pages are,
+  and what people are searching for.
 
 ⏩️ :doc:`/user-defined-redirects`
   Projects may define their own custom URL redirects,
   with advanced functionality like folder redirects.
 
+⏩️ :doc:`/commercial/sharing`
+  It is possible to host private and password protected documentation on Read the Docs for Business.
+
 ⏩️ :doc:`/reference/cdn`
   Documentation projects are primarily static HTML pages along with media files.
   This allows us to cache them with our CDN,
   making them *load faster* for your users.
 
-
 ⏩️ :doc:`/reference/sitemaps`
   Sitemaps are generated and hosted automatically,
   improving search engine optimization.
   This helps your users find content more effectively on your site.
 
-
 ⏩️ :doc:`/reference/404-not-found`
   A 404 page is served when we can't find a page on your site.
   We provide a default 404 page,
   but you can also customize it.
 
-
 ⏩️ :doc:`/reference/robots`
   `robots.txt` files allow you to customize how your documentation is indexed in search engines.
   We provide a default robots.txt file,
   but you can also customize it.
 
-
-⏩️ :doc:`/commercial/sharing`
-  It is possible to host private and password protected documentation on Read the Docs for Business.
-
 .. The TOC here will be refactored once we reorganize the files in docs/user/.
 .. Probably, all feature reference should be in this directory!
 .. In upcoming work, redirects will be added for old URL destinations.
@@ -60,31 +64,30 @@ Hosting features
 
 .. toctree::
    :maxdepth: 1
-   :glob:
+   :caption: Hosting features
 
-   ../features
-   analytics
-   /server-side-search/index
-   /automation-rules
+   /custom-domains
+   /versions
+   /pull-requests
+   /build-notifications
    /user-defined-redirects
-   /badges
+   /reference/analytics
+   /commercial/sharing
    /reference/cdn
+   /reference/sitemaps
    /reference/404-not-found
    /reference/robots
-   /reference/sitemaps
-   /security-log
 
-   /config-file/index
-   /integrations
-   /versions
+   /server-side-search/index
+   /automation-rules
+   /badges
+   /security-log
+   /single_version
 
-   /builds
-   /build-customization
-   /environment-variables
+   /reference/environment-variables
    /flyout-menu
    /canonical-urls
    /feature-flags
    /commercial/organizations
    /commercial/privacy-level
-   /commercial/sharing
    /commercial/single-sign-on

docs/user/science.rst

@@ -24,7 +24,7 @@ Documentation and technical writing are broad fields.
 Their tools and practices have grown relevant to most scientific activities.
 This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses.
 
-Here's a brief overview of some :doc:`features <features>` that people in science and academic writing love about Read the Docs:
+Here's a brief overview of some :doc:`features </reference/features>` that people in science and academic writing love about Read the Docs:
 
 .. dropdown:: 🪄 Easy to use
     :open:

docs/user/tutorial/index.rst

@@ -665,7 +665,7 @@ Here you have some resources to continue learning about documentation
 and Read the Docs:
 
 - You can learn more about the functionality of the platform
-  by going over our :doc:`/features` page.
+  by going over our :doc:`features </reference/features>` page.
 - To make the most of the documentation generators that are supported,
   you can read the :doc:`Sphinx tutorial <sphinx:tutorial/index>`
   or the `MkDocs User Guide <https://www.mkdocs.org/user-guide/>`_.