Add missing doc redirects and a CI check for them

.github/workflows/ci-additional.yaml

@@ -435,6 +435,47 @@ jobs:
         run: |
           pixi run generate-ops-ci
 
+  check-doc-redirects:
+    name: Check redirects of moved doc pages
+    runs-on: ubuntu-latest
+    needs: detect-ci-trigger
+    if: needs.detect-ci-trigger.outputs.triggered == 'false'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0 # The check looks at every page ever added to doc/.
+          persist-credentials: false
+
+      # Every page ever added to doc/ must still exist or be redirected in
+      # rediraffe_redirects in doc/conf.py, so that links to old URLs keep working.
+      - name: Check that moved or removed doc pages are redirected
+        shell: bash
+        run: |
+          # Page names: paths below doc/ without suffix, skipping _build, _static, ...
+          pages() {
+            grep -E '\.(rst|md|ipynb)$' | grep -vE '/[_.]' |
+              sed -E 's#^doc/##; s#\.(rst|md|ipynb)$##' | sort -u
+          }
+          # Pages that were removed on purpose and have no successor in the docs.
+          removed_pages=(
+            getting-started                    # xray v0.1 docs
+            tutorial                           # xray v0.1 docs
+            team                               # moved to https://xarray.dev/team (GH7061)
+            sphinxext/ipython_sphinxext/README # vendored sphinx extension
+          )
+          ever=$(git log --format= --name-only --no-renames --diff-filter=A -- doc | pages)
+          known=$({
+            git ls-files doc
+            sed -n '/^rediraffe_redirects = {/,/^}/s#^ *"\([^"]*\)":.*#doc/\1#p' doc/conf.py
+            printf 'doc/%s.rst\n' "${removed_pages[@]}"
+          } | pages)
+          missing=$(comm -23 <(echo "$ever") <(echo "$known"))
+          if [ -n "$missing" ]; then
+            echo "These doc pages were removed or moved without a redirect in doc/conf.py:"
+            echo "$missing"
+            exit 1
+          fi
+
   zizmor:
     name: GHA Security Analysis using Zizmor
     runs-on: ubuntu-latest

doc/conf.py

@@ -322,6 +322,18 @@
     "duckarrays.rst": "user-guide/duckarrays.rst",
     "related-projects.rst": "user-guide/ecosystem.rst",
     "faq.rst": "get-help/faq.rst",
+    "getting-started-guide/faq.rst": "get-help/faq.rst",
+    "help-diagram.rst": "get-help/help-diagram.rst",
+    "howdoi.rst": "get-help/howdoi.rst",
+    "ecosystem.rst": "user-guide/ecosystem.rst",
+    "tutorials-and-videos.rst": "getting-started-guide/tutorials-and-videos.rst",
+    "quickstart.rst": "getting-started-guide/quick-overview.rst",
+    "examples/quick-overview.rst": "getting-started-guide/quick-overview.rst",
+    "why-xray.rst": "getting-started-guide/why-xarray.rst",
+    "whats_new.rst": "whats-new.rst",
+    "examples.rst": "gallery.rst",
+    "internals.rst": "internals/index.rst",
+    "internals/variable-objects.rst": "internals/internal-design.rst",
     "why-xarray.rst": "getting-started-guide/why-xarray.rst",
     "installing.rst": "getting-started-guide/installing.rst",
     "quick-overview.rst": "getting-started-guide/quick-overview.rst",

doc/whats-new.rst

@@ -406,6 +406,10 @@ Documentation
   (:issue:`10832`, :pull:`11156`).
   By `dolliecoder <https://github.com/dolliecoder>`_ and
   `Michael Niklas <https://github.com/headtr1ck>`_.
+- Restore the old URLs of documentation pages that were moved without a
+  redirect, e.g. the tutorials, FAQ and "how do I" pages, and check in CI that
+  moved or removed pages get a redirect (:issue:`11790`, :pull:`11794`).
+  By `Michael Niklas <https://github.com/headtr1ck>`_.
 
 Performance
 ~~~~~~~~~~~