Merge Diataxis into main!

CHANGELOG.rst

@@ -4789,7 +4789,7 @@ Version 2.1.5
  * `@stsewd <https://github.com/stsewd>`__: Move project description to the top (`#3510 <https://github.com/readthedocs/readthedocs.org/pull/3510>`__)
  * `@RichardLitt <https://github.com/RichardLitt>`__: Docs: Rename "Good First Bug" to "Good First Issue" (`#3505 <https://github.com/readthedocs/readthedocs.org/pull/3505>`__)
  * `@stsewd <https://github.com/stsewd>`__: Fix regex for getting project and user (`#3501 <https://github.com/readthedocs/readthedocs.org/pull/3501>`__)
- * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in BitBucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
+ * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in Bitbucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
  * `@andrewgodwin <https://github.com/andrewgodwin>`__: "stable" appearing to track future release branches (`#3268 <https://github.com/readthedocs/readthedocs.org/issues/3268>`__)
  * `@cdeil <https://github.com/cdeil>`__: No module named pip in conda build (`#2827 <https://github.com/readthedocs/readthedocs.org/issues/2827>`__)
  * `@Yaseenh <https://github.com/Yaseenh>`__: building project does not generate new pdf with changes in it (`#2758 <https://github.com/readthedocs/readthedocs.org/issues/2758>`__)
@@ -4806,7 +4806,7 @@ Version 2.1.4
  * `@davidfischer <https://github.com/davidfischer>`__: Small formatting change to the Alabaster footer (`#3491 <https://github.com/readthedocs/readthedocs.org/pull/3491>`__)
  * `@matsen <https://github.com/matsen>`__: Fixing "resetting" misspelling. (`#3487 <https://github.com/readthedocs/readthedocs.org/pull/3487>`__)
  * `@ericholscher <https://github.com/ericholscher>`__: Add David to dev team listing (`#3485 <https://github.com/readthedocs/readthedocs.org/pull/3485>`__)
- * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in BitBucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
+ * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in Bitbucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
  * `@ericholscher <https://github.com/ericholscher>`__: Use semvar for readthedocs-build to make bumping easier (`#3475 <https://github.com/readthedocs/readthedocs.org/pull/3475>`__)
  * `@davidfischer <https://github.com/davidfischer>`__: Add programming languages (`#3471 <https://github.com/readthedocs/readthedocs.org/pull/3471>`__)
  * `@humitos <https://github.com/humitos>`__: Remove TEMPLATE_LOADERS since it's the default (`#3469 <https://github.com/readthedocs/readthedocs.org/pull/3469>`__)

docs/_static/js/expand_tabs.js

@@ -1,9 +1,13 @@
 /*
  * Expands a specific tab of sphinx-tabs.
  * Usage:
- * - docs.readthedocs.io/?tab=Name
- * - docs.readthedocs.io/?tab=Name#section
- * Where 'Name' is the title of the tab (case sensitive).
+ * 1) docs.readthedocs.io/?tab=Name
+ * 2) docs.readthedocs.io/?tab=Name#section
+ * 3) docs.readthedocs.io/page#sphinx-label
+ * In 1) and 2), 'Name' is the title of the tab (case sensitive).
+ *
+ * In 3), you need to add a sphinx reference inside the tab.
+ * It mimics how sections are referenced and can be refactored.
 */
 $( document ).ready(function() {
   const urlParams = new URLSearchParams(window.location.search);
@@ -14,4 +18,20 @@ $( document ).ready(function() {
       tab.click();
     }
   }
+
+  // Uses a hash referencing a Sphinx label from the URL page#sphinx-label
+  var hash = window.location.hash.substr(1);
+  hash = hash.replace(/[^0-9a-z\-_]/gi, '');
+  // If the hash is inside a tab panel
+  var tab_with_reference = $(".sphinx-tabs-panel #" + hash).parents(".sphinx-tabs-panel");
+
+  if (tab_with_reference.length > 0) {
+    // Use the panel's ID to guess the tab's ID
+    var panel_id = tab_with_reference.first().attr("id");
+    var tab_id = panel_id.replace("panel-", "tab-");
+    // Invoke the tab buttons click() method to display it
+    $("button#" + tab_id).click();
+    // Scroll the tab widget into view
+    $('html, body').animate({ scrollTop: tab_with_reference.parents(".sphinx-tabs").first().offset().top}, 1000);
+  }
 });

docs/conf.py

@@ -21,6 +21,7 @@
     "multiproject",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinxcontrib.httpdomain",
     "sphinxcontrib.video",
@@ -58,8 +59,9 @@
 copyright = "Read the Docs, Inc & contributors"
 version = "9.5.0"
 release = version
-exclude_patterns = ["_build", "shared"]
+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),
@@ -147,8 +149,11 @@
 hoverxref_domains = ["py"]
 hoverxref_roles = [
     "option",
-    "doc",  # Documentation pages
-    "term",  # Glossary terms
+    # Documentation pages
+    # Not supported yet: https://github.com/readthedocs/sphinx-hoverxref/issues/18
+    "doc",
+    # Glossary terms
+    "term",
 ]
 hoverxref_role_types = {
     "mod": "modal",  # for Python Sphinx Domain
@@ -201,5 +206,9 @@
     r"https://readthedocs\.org/accounts/gold",
 ]
 
+extlinks = {
+    "rtd-issue": ("https://github.com/readthedocs/readthedocs.org/issues/%s", "#%s"),
+}
+
 # Disable epub mimetype warnings
 suppress_warnings = ["epub.unknown_project_files"]

docs/dev/install.rst

@@ -196,7 +196,7 @@ Configuring connected accounts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These are optional steps to setup the :doc:`connected accounts <rtd:connected-accounts>`
-(GitHub, GitLab, and BitBucket) in your development environment.
+(GitHub, GitLab, and Bitbucket) in your development environment.
 This will allow you to login to your local development instance
 using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.

docs/user/_includes/organization-permissions.rst

@@ -0,0 +1,13 @@
+Organization permissions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change your :doc:`Organization's </commercial/organizations>` settings,
+you need to be an *owner* of that organization.
+
+You can validate your ownership of the Organization with these steps:
+
+* Navigate to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Organization name>`
+* Look at the :guilabel:`Owners` section on the right menu.
+
+If you'd like to modify this setting and are not an owner,
+you can ask an existing organization owner to take the actions listed.

docs/user/abandoned-projects.rst

@@ -1,5 +1,5 @@
-Policy for Abandoned Projects
-=============================
+Abandoned projects policy
+=========================
 
 This policy describes the process by which a Read the Docs project :term:`slug` may be changed.
 

docs/user/about.rst → docs/user/about/index.rst

@@ -4,7 +4,7 @@ About Read the Docs
 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.
-This allows us to **focus 100% on our users**. 
+This allows us to **focus 100% on our users**.
 
 We have two main sources of revenue:
 
@@ -25,3 +25,51 @@ 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>`.
+
+If you want to dive more into more specific information and our policies,
+we've brought most of the most important ones below.
+
+⏩ :doc:`/commercial/index`
+   Learn more about how our company provides paid solutions
+
+⏩ :doc:`/reference/policies`
+   Policies and legal documents used by |org_brand| and |com_brand|.
+
+⏩ :doc:`/advertising/index`
+   Information about how advertisement in Read the Docs
+
+⏩ :doc:`/story`
+   A brief throwback to how we were founded
+
+⏩ :doc:`/sponsors`
+   Read about who currently sponsors Read the Docs and who sponsored us in the past.
+
+⏩ :doc:`/open-source-philosophy`
+   Our philosophy is anchored in open source.
+
+⏩ :doc:`/team`
+   How we work and who we are.
+
+⏩ :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/analytics.rst

@@ -1,5 +1,8 @@
-Traffic Analytics
-=================
+How to use traffic analytics
+============================
+
+In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
+You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
 
 Traffic Analytics lets you see *which* documents your users are reading.
 This allows you to understand how your documentation is being used,

docs/user/api/index.rst

@@ -12,4 +12,5 @@ from Read the Docs.
 
    v3
    v2
+   /server-side-search/api
    cross-site-requests

docs/user/api/v3.rst

@@ -1654,7 +1654,7 @@ Remote Organizations
 ~~~~~~~~~~~~~~~~~~~~
 
 Remote Organizations are the VCS organizations connected via
-``GitHub``, ``GitLab`` and ``BitBucket``.
+``GitHub``, ``GitLab`` and ``Bitbucket``.
 
 
 Remote Organization listing
@@ -1717,7 +1717,7 @@ Remote Repositories
 ~~~~~~~~~~~~~~~~~~~
 
 Remote Repositories are the importable repositories connected via
-``GitHub``, ``GitLab`` and ``BitBucket``.
+``GitHub``, ``GitLab`` and ``Bitbucket``.
 
 
 Remote Repository listing

docs/user/automatic-redirects.rst

@@ -1,60 +1,92 @@
-Automatic Redirects
-===================
+.. old reference
 
-Read the Docs supports redirecting certain URLs automatically.
-This is an overview of the set of redirects that are fully supported and will work into the future.
+.. _Automatic Redirects:
 
-Redirecting to a Page
----------------------
+Best practices for linking to your documentation
+================================================
 
-You can link to a specific page and have it redirect to your default version.
-This is done with the ``/page/`` URL prefix.
-You can reach this page by going to https://docs.readthedocs.io/page/automatic-redirects.html.
+Once you start to publish documentation,
+external sources will inevitably link to specific pages in your documentation.
 
-This allows you to create links that are always up to date.
+Sources of incoming links vary greatly depending on the type of documentation project that is published.
+They can include everything from old emails to GitHub issues, wiki articles, software comments, PDF publications, or StackOverflow answers.
+Most of these incoming sources are not in your control.
 
-Another way to handle this is the ``latest`` version.
-You can set your ``latest`` version to a specific version and just always link to ``latest``.
-You can read more about this in our :doc:`versions </versions>` page.
+Read the Docs makes it easier to create and manage incoming links by redirecting certain URLs automatically
+and giving you access to define your own redirects.
 
-Root URL
---------
+In this article,
+we explain how our built-in redirects work and what we consider "best practice" for managing incoming links.
 
-A link to the root of your documentation will redirect to the *default version*,
-as set in your project settings.
-For example::
+.. seealso::
 
-    docs.readthedocs.io -> docs.readthedocs.io/en/latest/
-    www.pip-installer.org -> www.pip-installer.org/en/latest/
+   :doc:`/versions`
+     Read more about how to handle versioned documentation and URL structures.
 
-This only works for the root URL, not for internal pages. It's designed to redirect people from ``http://pip.readthedocs.io/`` to the default version of your documentation, since serving up a 404 here would be a pretty terrible user experience. (If your "develop" branch was designated as your default version, then it would redirect to ``http://pip.readthedocs.io/en/develop``.) But, it's not a universal redirecting solution. So, for example, a link to an internal page like ``http://pip.readthedocs.io/usage.html`` doesn't redirect to ``http://pip.readthedocs.io/en/latest/usage.html``.
+   :doc:`/user-defined-redirects`
+     Overview of all the redirect features available on Read the Docs.
+     Many of the redirect features are useful either for building external links or handling requests to old URLs.
 
-The reasoning behind this is that RTD organizes the URLs for docs so that multiple translations and multiple versions of your docs can be organized logically and consistently for all projects that RTD hosts. For the way that RTD views docs, ``http://pip.readthedocs.io/en/latest/`` is the root directory for your default documentation in English, not ``http://pip.readthedocs.io/``. Just like ``http://pip.readthedocs.io/en/develop/`` is the root for your development documentation in English.
+   :doc:`/guides/redirects`
+     How to add a user-defined redirect, step-by-step.
+     Useful if your content changes location!
 
-Among all the multiple versions of docs, you can choose which is the "default" version for RTD to display, which usually corresponds to the git branch of the most recent official release from your project.
 
-rtfd.io
-~~~~~~~~
+Best practice: "permalink" your pages
+-------------------------------------
 
-Links to rtfd.io are treated the same way as above.
-They redirect the root URL to the default version of the project.
-They are intended to be easy and short for people to type.
+You might be familiar with the concept of `permalinks`_ from blogging.
+The idea is that a blog post receives a unique link as soon as it's published and that the link does not change afterward.
+Incoming sources can reference the blog post even though the blog changes structure or the post title changes.
 
-You can reach these docs at https://docs.rtfd.io.
+When creating an external link to a specific documentation page,
+chances are that the page is moved as the documentation changes over time.
 
-Supported Top-Level Redirects
------------------------------
+How should a permalink look for a documentation project?
+Firstly, you should know that a *permalink* does not really exist in documentation but it is the result of careful actions to avoid breaking incoming links.
 
-.. note:: These "implicit" redirects are supported for legacy reasons.
-          We will not be adding support for any more magic redirects.
-          If you want additional redirects,
-          they should live at a prefix like `Redirecting to a Page`_
+As a documentation owner,
+you most likely want users clicking on incoming links to see the latest version of the page.
 
-The main challenge of URL routing in Read the Docs is handling redirects correctly. Both in the interest of redirecting older URLs that are now obsolete, and in the interest of handling "logical-looking" URLs (leaving out the lang_slug or version_slug shouldn't result in a 404), the following redirects are supported::
+.. _permalinks: https://en.wikipedia.org/wiki/Permalink
 
-    /          -> /en/latest/
-    /en/       -> /en/latest/
-    /latest/   -> /en/latest/
+Good practice ✅
+~~~~~~~~~~~~~~~~
 
-The language redirect will work for any of the defined ``LANGUAGE_CODES`` we support.
-The version redirect will work for supported versions.
+* Use `page redirects <user-defined-redirects:Page redirects>`_ if you are linking to the page in the :term:`default version` of the default language. This allows links to continue working even if those defaults change.
+* If you move a page that likely has incoming references, :doc:`create a custom redirect rule </guides/redirects>`.
+* Links to other Sphinx projects should use :doc:`intersphinx </guides/intersphinx>`.
+* Use minimal filenames that don't require renaming often.
+* When possible,
+  keep original file names rather than going for low-impact URL renaming.
+  Renaming an article's title is great for the reader and great for SEO,
+  but this does not have to involve the URL.
+* Establish your understanding of the *latest* and *:term:`default version`* of your documentation at the beginning. Changing their meaning is very disruptive to incoming links.
+* Keep development versions :ref:`hidden <versions:Hidden>` so people do not find them on search engines by mistake.
+  This is the best way to ensure that nobody links to URLs that are intended for development purposes.
+* Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
+
+.. tip::
+
+   Using Sphinx?
+     If you are using ``:ref:`` for :doc:`cross-referencing </guides/cross-referencing-with-sphinx>`, you may add as many reference labels to a headline as you need,
+     keeping old reference labels. This will make refactoring documentation easier and avoid that external projects
+     referencing your documentation through :doc:`intersphinx </guides/intersphinx>` break.
+
+Questionable practice 🟡
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Avoid using specific versions in links unless users need that exact version.
+  Versions get outdated.
+* Avoid using a public ``latest`` for development versions and do not make your *default version* a development branch.
+  Publishing development branches can mean that users are reading instructions for unreleased software or draft documentation.
+
+.. tip::
+
+   404 pages are also okay!
+     If documentation pages have been removed or moved,
+     it can make the maintainer of the referring website aware that they need to update their link.
+     Users will be aware that the documentation **project** still exists but has changed.
+
+     The default Read the Docs 404 page is designed to be helpful,
+     but you can also design your own, see :ref:`hosting:Custom Not Found (404) Pages`.