Skip to content

DOCS: Adopt sphinxext-rediraffe for redirects - #3043

Merged
VeckoTheGecko merged 1 commit into
Parcels-code:mainfrom
VeckoTheGecko:sphinx-redirect
Nov 5, 2026
Merged

VeckoTheGecko merged 1 commit into
Parcels-code:mainfrom
VeckoTheGecko:sphinx-redirect

Conversation

@VeckoTheGecko

@VeckoTheGecko VeckoTheGecko commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adopts sphinxext-rediraffe so that docs pages can be moved or deleted without breaking existing links.

  • Adds sphinxext-rediraffe to the docs Pixi environment and enables it in docs/conf.py.
  • Adds an empty rediraffe_redirects = {} dict to docs/conf.py. Entries map old paths to new paths, relative to docs/, e.g. "user_guide/examples/tutorial_old.ipynb": "user_guide/examples/tutorial_new.ipynb". It's empty for now because no pages have been moved or deleted since v4.0.0. URLs from the v3 docs aren't redirected, since they still work under their own Read the Docs version.
  • Adds a sentence to the development guide asking contributors to add an entry when they move or delete a page.

During the HTML build, rediraffe writes a small redirect page for each entry, e.g. old.html that forwards to new.html and keeps the query string and anchor. Chained redirects are resolved, so users are redirected at most once.

This follows CPython's setup, which also keeps a dict in conf.py and relies on review to catch missing redirects. rediraffe also has builders that check git for renamed or deleted pages without a redirect, but I left those out to keep this simple. Pages rarely move, and a reviewer can spot renames and deletions in the PR's file list.

Testing: I built the HTML docs (without running the notebooks) with:

  1. the empty dict: the build succeeds and rediraffe gives no warnings.
  2. a temporary entry "old_installation.md": "user_guide/getting_started/installation.md" (not included in this PR): the build creates old_installation.html, which redirects to the installation page.

Checklist

AI Disclosure

  • This PR contains AI-generated content.
    • I have tested any AI-generated content in my PR.
    • I take responsibility for any AI-generated content in my PR.
    • Describe how you used it (e.g., by pasting your prompt): Claude Code (Opus 5.5) was asked to "branch off of main that adopts https://sphinxext-rediraffe.readthedocs.io/". It made the changes and ran the testing described above. I chose the scope: no v3 backfill, and a minimal CPython-style setup without the redirect-checking builders.

🤖 Generated with Claude Code

Redirects for moved/deleted docs pages can now be added to
rediraffe_redirects in docs/conf.py.
@VeckoTheGecko

Copy link
Copy Markdown
Contributor Author

merging, will test in the other PR

@VeckoTheGecko
VeckoTheGecko merged commit 4fef7f1 into Parcels-code:main Nov 5, 2026
20 of 21 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Parcels development Nov 5, 2026
@VeckoTheGecko
VeckoTheGecko deleted the sphinx-redirect branch November 5, 2026 14:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant