All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading