# Add Redirects for Moved Pages to Sphinx Docs

Yes. An agent finds the pages your Sphinx docs deleted or renamed, adds sphinx-reredirects with a redirect for each, keeps the strict build green and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-redirects/sphinx/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the docs build and its history before it writes a redirect. In a project like python-attrs/attrs, `docs/conf.py` lists `myst_parser`, `sphinx.ext.napoleon`, `autodoc`, `doctest`, `intersphinx`, `todo`, `notfound.extension` and `sphinxcontrib.towncrier` as extensions, sets `html_theme = "furo"`, reads `html_baseurl` from the `READTHEDOCS_CANONICAL_URL` environment variable and keeps `source_suffix = ".rst"` with MyST handling the `.md` pages. The docs dependencies are the `docs` group in `pyproject.toml`, locked in `uv.lock`, and `tox.ini` builds with `sphinx-build -n -T -W -b html docs docs/_build/html` in `docs-build`, so any warning fails, with a `docs-linkcheck` environment beside it; `.readthedocs.yaml` runs the same tox environment through `uv`. `notfound.extension` is already there, so a missing page gets a styled 404, but nothing sends a reader on.

The old URLs come from git. The agent runs `git log --diff-filter=D --name-status -- docs` and `git log --diff-filter=R` over the docs directory and finds that every `.rst` page was replaced by a `.md` page of the same name in late 2022, which kept each URL, and that three pages went away with no successor: `python-2.rst` in March 2022, and `backward-compatibility.rst` and `contributing.rst` in November 2021. Each still has a `.html` address that was linked from elsewhere for years. The agent reads each deleted file's last content with `git show` to choose a target: the Python 2 page and the backward compatibility page go to the sections of `changelog.md` or `index.md` that now carry that material, and the contributing page goes to `.github/CONTRIBUTING.md` on GitHub, an external URL, which the extension supports. The choices are listed in the pull request for the reviewer to change.

sphinx-reredirects, at 1.1.0 the current release, is the extension. Its documentation says to add `sphinx_reredirects` to `extensions` and a `redirects` dict in `conf.py` mapping a source docname, the path without its suffix, to a target: a relative or absolute path within the site, or a full URL, and that for the `html` builder the target of a page is `name.html`. For each source it writes an HTML file holding `<meta http-equiv="refresh" content="0; url=...">`, so no server configuration is needed, it does nothing for builders that are not HTML, and it hands redirects to external URLs to the `linkcheck` builder. The agent adds `sphinx-reredirects` to the `docs` group in `pyproject.toml`, runs `uv lock`, appends the extension and the three-entry `redirects` dict to `conf.py` with a comment pointing at the git commands that found them.

Then it builds the way Read the Docs does, `uv run --only-group tox tox run -e docs-build`, which must end with no warning under `-W`, reads `docs/_build/html/python-2.html`, `backward-compatibility.html` and `contributing.html` for their refresh tags, runs `docs-linkcheck` and shows the contributing redirect checked as an external link with line `-1`, and serves `docs/_build/html` to open an old address in its own browser and land on the new page. It also runs `docs-doctests`, the environment CI runs, to show nothing else moved, and adds a line to the docs section of `.github/CONTRIBUTING.md` saying where a renamed page gets its redirect.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add redirects for the pages this project's Sphinx documentation has deleted or renamed. Read docs/conf.py, pyproject.toml, uv.lock, tox.ini, .readthedocs.yaml, .github/workflows/ci.yml, .github/CONTRIBUTING.md and the docs directory first, then use git log with --diff-filter=D and --diff-filter=R over docs to list every page whose URL no longer builds, and read each deleted page's last content to choose the nearest current page or external URL as its target. Add sphinx-reredirects to the docs dependency group and update the lock file; in conf.py enable sphinx_reredirects and a redirects dict with one entry per old page, with a comment naming the commands that found them. Build with the tox docs-build environment, which treats warnings as errors, read the generated redirect files, run docs-linkcheck and docs-doctests, open an old URL in a browser and confirm it lands on the new page, add a line to the docs section of CONTRIBUTING.md, and open a pull request linking the issue that lists each redirect with the commit that removed its page and the reason for its target.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `docs/conf.py`, `pyproject.toml`, `uv.lock` and `.github/CONTRIBUTING.md`. Its description holds a table of each old docname, the commit and date that removed it, the target chosen and why, then the `tox run -e docs-build` output ending without warnings, the three generated files' refresh tags, the `docs-linkcheck` lines for the external target and the `docs-doctests` result. No page source changes.

A reviewer checks each target, since the agent chose them from the deleted pages' last content and the choice is editorial, and whether the project would rather keep redirects in the Read the Docs dashboard, which the pull request mentions as the alternative that does not travel with the repository. After merging, the next Read the Docs build serves the three old addresses as redirects, and a future rename is one more line in the dict.

## Run it on every Linear issue labelled docs

An automation in the Project that holds the repository takes a `linear` trigger on `linear.issue.labeled` with the label `docs`. Its runs are read-only, so the saved prompt asks for a plan: the run runs the git history queries, lists the pages that vanished and the target it would give each, and posts that as a comment on the issue, where the editorial choices get discussed before anything is written. A handler on the team's own server then starts the run that writes the pull request, sending this body with the issue's URL added to `resources` and a `request_id` that is a UUID v5 of the issue id, so a retried start returns the run already started.

A team with several Sphinx projects sends one request per repository, each with its own `resources` entry.

## Why run it on Rush?

Finding the broken addresses is history work, not a search of the current tree: the pages are gone, and only `git log` with the right filters says which, when, and what they said. The agent runs those queries, reads the old content to pick targets, and proves the result with the project's own strict build, the link checker and a browser landing on the new page, all in its own sandbox with every command and its output kept in the run's record.

It also fits the project's build rather than adding a layer beside it: the `docs` dependency group and the lock that tox reads, the `-W` build Read the Docs runs, the 404 extension that stays for pages nobody can redirect. Ten projects with ten histories get ten pull requests, each with that project's own list of moved pages.

## Frequently asked questions

### Why not configure redirects on Read the Docs instead?

Read the Docs can redirect from its dashboard, and the pull request says so. The dict in `conf.py` is reviewed like code, travels with a fork or a move to another host, and is what the `docset` tox environment packs when it builds the offline docs, which dashboard rules never reach.

### Will the strict build complain about a redirect?

The extension writes plain HTML files after the build and emits no warning for a source docname that does not exist, so the `-W` build passes. The agent runs `docs-build` to show it, and a redirect that overwrites an existing page is the one case to review, which the wildcard syntax makes possible on purpose.

### Does it check that the targets exist?

An external target is checked by `docs-linkcheck`, which the extension cooperates with. A target inside the same site is not, so the agent opens each generated redirect in its browser and confirms it lands on a page that builds, and the pull request lists the three landings.

### What about pages renamed from .rst to .md?

Those keep their docname and therefore their URL, so they need no redirect; the agent's history query shows them and leaves them out. Only a page whose docname changed or disappeared gets an entry.

## More Sphinx jobs

- [Add a Sitemap to a Sphinx Docs Site](https://getrush.ai/run/add-sitemap/sphinx/)
- [Add Social Cards to Sphinx Docs](https://getrush.ai/run/add-social-cards/sphinx/)
- [Add a Typo Check to a Sphinx Documentation Site](https://getrush.ai/run/add-typo-check/sphinx/)

## The same job on other stacks

- [Add Redirects for Moved Pages to a Docusaurus Site](https://getrush.ai/run/add-redirects/docusaurus/)
- [Add Redirects for Moved Pages to an mdBook](https://getrush.ai/run/add-redirects/mdbook/)
- [Add Redirects for Moved Pages to a MkDocs Site](https://getrush.ai/run/add-redirects/mkdocs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
