Allow us to manage documentation redirects (#2372)

Author: ssbarnea

.github/workflows/redirects.yml

@@ -0,0 +1,33 @@
+---
+# Sync RTD redirects
+name: redirects
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/redirects.yml
+      - .github/workflows/redirects.yml
+
+  # Manually triggered using GitHub's UI
+  workflow_dispatch:
+
+jobs:
+  docs:
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v4
+
+      - name: Upgrade Python toolchain
+        run: python3 -m pip install --upgrade pip setuptools wheel
+
+      - name: Install readthedocs-cli
+        run: python3 -m pip install readthedocs-cli
+
+      - name: Sync redirects
+        run: rtd projects ansible-lint redirects sync -f docs/redirects.yml --wet-run
+        env:
+          RTD_TOKEN: ${{ secrets.RTD_TOKEN }}

docs/conf.py

@@ -178,6 +178,8 @@
 html_theme_options = {
     "collapse_navigation": False,
     "analytics_id": "UA-128382387-1",
+    # cspell:disable-next-line
+    "tag_manager_id": "GTM-5FGNF6S",
     "style_nav_header_background": "#5bbdbf",
     "style_external_links": True,
     # 'canonical_url': "https://docs.ansible.com/ansible/latest/",

docs/redirects.yml

@@ -0,0 +1,16 @@
+# Authoritative list of redirects we have configured in RTD,
+# https://pypi.org/project/readthedocs-cli/
+---
+- type: page
+  from_url: /rules/git-latest/
+  to_url: /rules/latest/
+- type: page
+  from_url: /rules/hg-latest/
+  to_url: /rules/latest/
+- type: page
+  from_url: /default_rules/index/
+  to_url: /rules/
+# Keep this last or it will match all the other rules
+- type: sphinx_htmldir
+  from_url: ""
+  to_url: ""

tox.ini

@@ -44,6 +44,7 @@ passenv =
   PYTEST_*  # allows developer to define their own preferences
   PYTEST_REQPASS  # needed for CI
   PY_COLORS
+  RTD_TOKEN
   REQUESTS_CA_BUNDLE  # https proxies
   SSL_CERT_FILE  # https proxies
   LANG
@@ -161,6 +162,14 @@ commands =
   'print("\n" + "=" * 120 + f"\n\nDocumentation available under `file://\{index_file\}`\n\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n\n" + "=" * 120)'
 changedir = {toxinidir}/docs
 
+[testenv:redirects]
+description = Update documentation redirections for readthedocs
+deps =
+  readthedocs-cli
+commands =
+  # This assumes you loaded RTD_TOKEN in your environment
+  rtd projects ansible-lint redirects sync -f docs/redirects.yml --wet-run
+
 [testenv:eco]
 description = Perform ecosystem impact (downstream testing) https://github.com/ansible-community/ansible-lint/discussions/1403
 skip_install = true