Manage RTD redirects through a version-controlled file

Fixes pypa#1408

.github/workflows/sync-rtd-redirects.yml

@@ -0,0 +1,28 @@
+name: Sync ReadTheDocs redirects
+
+on:
+  push:
+    branches:
+      - main
+      - redirects ## TEMP
+    paths:
+      - .readthedocs-redirects.yaml
+      - .github/workflows/sync-rtd-redirects.yml
+
+jobs:
+  sync:
+    if: ${{ github.repository_owner == 'jeanas' }} ## TEMP
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install readthedocs-cli
+        run: pipx install readthedocs-cli
+      - name: Sync redirects
+        env:
+          RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
+        run: |
+          rtd projects rtd-redirects-test \
+            redirects sync \
+            -f .readthedocs-redirects.yaml \
+            --wet-run

.readthedocs-redirects.yaml

@@ -0,0 +1,204 @@
+# This file contains declares all redirects, which are automatically synced to
+# ReadTheDocs. Whenever a page is moved, a redirect should be added here,
+# normally with the "page" type, so that existing links continue to
+# work. Redirect types are documented on
+# https://docs.readthedocs.io/en/stable/user-defined-redirects.html#user-defined-redirects
+
+# WARNING: Page redirects currently need to be declared in two versions, without
+# and with a trailing slash.
+# https://github.com/readthedocs/readthedocs.org/issues/10962
+
+- type: page
+  from_url: /additional
+  to_url: /guides/
+- type: page
+  from_url: /additional/
+  to_url: /guides/
+
+- type: page
+  from_url: /appveyor
+  to_url: /guides/supporting-windows-using-appveyor/
+- type: page
+  from_url: /appveyor/
+  to_url: /guides/supporting-windows-using-appveyor/
+
+- type: page
+  from_url: /current
+  to_url: /guides/tool-recommendations/
+- type: page
+  from_url: /current/
+  to_url: /guides/tool-recommendations/
+
+- type: page
+  from_url: /deployment
+  to_url: /discussions/deploying-python-applications/
+- type: page
+  from_url: /deployment/
+  to_url: /discussions/deploying-python-applications/
+
+- type: page
+  from_url: /distributing
+  to_url: /tutorials/packaging-projects/
+- type: page
+  from_url: /distributing/
+  to_url: /tutorials/packaging-projects/
+
+- type: page
+  from_url: /extensions
+  to_url: /guides/packaging-binary-extensions/
+- type: page
+  from_url: /extensions/
+  to_url: /guides/packaging-binary-extensions/
+
+- type: page
+  from_url: /guides/installing-using-pip-and-virtualenv
+  to_url: /guides/installing-using-pip-and-virtual-environments/
+- type: page
+  from_url: /guides/installing-using-pip-and-virtualenv/
+  to_url: /guides/installing-using-pip-and-virtual-environments/
+
+- type: page
+  from_url: /install_requirements_linux
+  to_url: /guides/installing-using-linux-tools/
+- type: page
+  from_url: /install_requirements_linux/
+  to_url: /guides/installing-using-linux-tools/
+
+- type: page
+  from_url: /installing
+  to_url: /tutorials/installing-packages/
+- type: page
+  from_url: /installing/
+  to_url: /tutorials/installing-packages/
+
+- type: page
+  from_url: /mirrors
+  to_url: /guides/index-mirrors-and-caches/
+- type: page
+  from_url: /mirrors/
+  to_url: /guides/index-mirrors-and-caches/
+
+- type: page
+  from_url: /multi_version_install
+  to_url: /guides/multi-version-installs/
+- type: page
+  from_url: /multi_version_install/
+  to_url: /guides/multi-version-installs/
+
+- type: page
+  from_url: /multiple_python_versions
+  to_url: /guides/supporting-multiple-python-versions/
+- type: page
+  from_url: /multiple_python_versions/
+  to_url: /guides/supporting-multiple-python-versions/
+
+- type: page
+  from_url: /namespace_packages
+  to_url: /guides/packaging-namespace-packages/
+- type: page
+  from_url: /namespace_packages/
+  to_url: /guides/packaging-namespace-packages/
+
+- type: page
+  from_url: /pip_easy_install
+  to_url: /discussions/pip-vs-easy-install/
+- type: page
+  from_url: /pip_easy_install/
+  to_url: /discussions/pip-vs-easy-install/
+
+- type: page
+  from_url: /platforms
+  to_url: /guides/installing-scientific-packages/
+- type: page
+  from_url: /platforms/
+  to_url: /guides/installing-scientific-packages/
+
+- type: page
+  from_url: /plugin_discovery
+  to_url: /guides/creating-and-discovering-plugins/
+- type: page
+  from_url: /plugin_discovery/
+  to_url: /guides/creating-and-discovering-plugins/
+
+- type: page
+  from_url: /quickstart
+  to_url: /tutorials/
+- type: page
+  from_url: /quickstart/
+  to_url: /tutorials/
+
+- type: page
+  from_url: /requirements
+  to_url: /discussions/install-requires-vs-requirements/
+- type: page
+  from_url: /requirements/
+  to_url: /discussions/install-requires-vs-requirements/
+
+- type: page
+  from_url: /science
+  to_url: /guides/installing-scientific-packages/
+- type: page
+  from_url: /science/
+  to_url: /guides/installing-scientific-packages/
+
+- type: page
+  from_url: /self_hosted_repository
+  to_url: /guides/hosting-your-own-index/
+- type: page
+  from_url: /self_hosted_repository/
+  to_url: /guides/creating-and-discovering-plugins/
+
+- type: page
+  from_url: /single_source_version
+  to_url: /guides/single-sourcing-package-version/
+- type: page
+  from_url: /single_source_version/
+  to_url: /guides/single-sourcing-package-version/
+
+- type: page
+  from_url: /specifications/declaring-build-dependencies
+  to_url: /specifications/pyproject-toml/
+- type: page
+  from_url: /specifications/declaring-build-dependencies/
+  to_url: /specifications/pyproject-toml/
+
+- type: page
+  from_url: /specifications/declaring-project-metadata
+  to_url: /specifications/pyproject-toml/
+- type: page
+  from_url: /specifications/declaring-project-metadata/
+  to_url: /specifications/pyproject-toml/
+
+- type: page
+  from_url: /tutorial
+  to_url: /tutorials/
+- type: page
+  from_url: /tutorial/
+  to_url: /tutorials/
+
+- type: page
+  from_url: /tutorials/distributing-packages
+  to_url: /tutorials/packaging-projects/
+- type: page
+  from_url: /tutorials/distributing-packages/
+  to_url: /en/latest/tutorials/packaging-projects/
+
+- type: page
+  from_url: /wheel_egg
+  to_url: /discussions/wheel-vs-egg/
+- type: page
+  from_url: /wheel_egg/
+  to_url: /discussions/wheel-vs-egg/
+
+
+# This redirects https://packaging.python.org/<docname>
+# to https://packaging.python.org/en/latest/<docname>
+# because URLs used to have the first form.
+
+- type: prefix
+  from_url: ''
+  to_url: ''
+
+- type: sphinx_htmldir
+  from_url: ''
+  to_url: ''