Redirects: improvements from design doc (#10881)

Implements https://dev.readthedocs.io/en/latest/design/redirects.html

docs/user/api/v3.rst

@@ -1145,6 +1145,11 @@ Redirect details
            "from_url": "/docs/",
            "to_url": "/documentation/",
            "type": "page",
+           "http_status": 302,
+           "description": "",
+           "enabled": true,
+           "force": false,
+           "position": 0,
            "_links": {
                "_self": "/api/v3/projects/pip/redirects/1/",
                "project": "/api/v3/projects/pip/"
@@ -1227,18 +1232,21 @@ Redirect create
         {
             "from_url": "/docs/",
             "to_url": "/documentation/",
-            "type": "page"
+            "type": "page",
+            "position": 0,
         }
 
     .. note::
 
-       ``type`` can be one of ``prefix``, ``page``, ``exact``, ``sphinx_html`` and ``sphinx_htmldir``.
+       - ``type`` can be one of ``page``, ``exact``, ``clean_url_to_html`` and ``html_to_clean_url``.
+       - Depending on the ``type`` of the redirect, some fields may not be needed:
 
-       Depending on the ``type`` of the redirect, some fields may not be needed:
+         * ``page`` and ``exact`` types require ``from_url`` and ``to_url``.
+         * ``clean_url_to_html`` and ``html_to_clean_url`` types do not require ``from_url`` and ``to_url``.
 
-       * ``prefix`` type does not require ``to_url``.
-       * ``page`` and ``exact`` types require ``from_url`` and ``to_url``.
-       * ``sphinx_html`` and ``sphinx_htmldir`` types do not require ``from_url`` and ``to_url``.
+       - Forced redirects are not enabled by default,
+         you can ask for them to be enabled via support.
+       - Position starts at 0 and is used to order redirects.
 
     **Example response**:
 
@@ -1291,6 +1299,11 @@ Redirect update
             "type": "page"
         }
 
+    .. note::
+
+       If the position of the redirect is changed,
+       it will be inserted in the new position and the other redirects will be reordered.
+
     **Example response**:
 
     `See Redirect details <#redirect-details>`_

docs/user/guides/redirects.rst

@@ -42,12 +42,6 @@ you can mark the choice in order to experiment and **preview** the final rule ge
 
 Here is a quick overview of the options available in :guilabel:`Redirect Type`:
 
-Prefix redirect
-  This option is often relevant when moving a project from a former host to Read the Docs.
-  In this case, often URL paths hierarchies are redirected.
-
-  Read more about this option in :ref:`user-defined-redirects:Prefix redirects`
-
 Page redirect
   With this option,
   you can specify a page in your documentation to redirect elsewhere.
@@ -64,18 +58,18 @@ Exact redirect
 
   Read more about this option in :ref:`user-defined-redirects:Exact redirects`
 
-Sphinx HTMLDir => HTML
-  If you choose to change your Sphinx builder from *DirHTML writer* to the default *html5writer*,
+Clean URL to HTML
+  If you choose to change the style of your URLs from *clean URLs* (``/en/latest/tutorial/``) to *HTML URLs* (``/en/latest/tutorial.html``),
   you can redirect all mismatches automatically.
 
-  Read more about this option in :ref:`user-defined-redirects:Sphinx redirects`
+  Read more about this option in :ref:`user-defined-redirects:Clean/HTML URLs redirects`
 
-Sphinx HTML => HTMLDir
+HTML to clean URL
   Similarly to the former option,
-  if you choose to change your Sphinx builder from the default *html5writer* to *DirHTML writer*,
+  if you choose to change the style of your URLs from *HTML URLs* (``/en/latest/tutorial.html``) to *clean URLs* (``/en/latest/tutorial/``),
   you can redirect all mismatches automatically.
 
-  Read more about this option in :ref:`user-defined-redirects:Sphinx redirects`
+  Read more about this option in :ref:`user-defined-redirects:Clean/HTML URLs redirects`
 
 .. note::
 
@@ -114,3 +108,15 @@ in order to delete a rule or edit it.
 
 When editing a rule,
 you can change its :guilabel:`Redirect Type` and its :guilabel:`From URL` or :guilabel:`To URL`.
+
+Changing the order of redirects
+-------------------------------
+
+The order of redirects is important,
+if you have multiple rules that match the same URL,
+the first redirect in the list will be used.
+
+You can change the order of the redirect from the :menuselection:`Admin > Redirects` page,
+by using the up and down arrow buttons.
+
+New redirects are added at the start of the list (i.e. they have the highest priority).