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,97 @@
+# This file contains declares all redirects, which are automatically synced to
+# ReadTheDocs. Whenever a page is moved, a redirect should be added here 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
+
+- type: page
+  from_url: /additional/
+  to_url: /guides/
+- type: page
+  from_url: /appveyor/
+  to_url: /guides/supporting-windows-using-appveyor/
+- type: page
+  from_url: /current.html
+  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: /distributing/
+  to_url: /tutorials/packaging-projects/
+- 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: /install_requirements_linux/
+  to_url: /guides/installing-using-linux-tools/
+- 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: /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: /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: /platforms/
+  to_url: /guides/installing-scientific-packages/
+- 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: /requirements/
+  to_url: /discussions/install-requires-vs-requirements/
+- type: page
+  from_url: /science/
+  to_url: /guides/installing-scientific-packages/
+- 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: /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: /tutorial/
+  to_url: /tutorials/
+- type: page
+  from_url: /tutorials/distributing-packages/
+  to_url: /tutorials/packaging-projects/
+- type: page
+  from_url: /wheel_egg/
+  to_url: /discussions/wheel-vs-egg/
+
+# This redirects https://packaging.python.org/... to https://packaging.python.org/en/latest/...
+# because URLs used to have the first form.
+
+- type: prefix
+  from_url: ''
+  to_url: ''
+
+- type: sphinx_htmldir
+  from_url: ''
+  to_url: ''