rtd-redirects
Manage Read the Docs redirects as code. A YAML file in your docs repo is the source of truth; this CLI reconciles it against the RtD v3 API.
Status
v0.1.0 in development. Built for docs.ray.io IA-cleanup campaigns; the patterns generalize to any RtD project. Design rationale and full architecture are in anyscale/docs:strategy/ray-docs/redirect-mgmt/.
Why
Read the Docs has no bulk redirect import. Its dashboard UI requires clicking through each entry by hand, which makes any meaningful slug-rename or IA-cleanup campaign untenable. rtd-redirects reads a YAML file from your repo, diffs it against the live RtD state, and applies the diff. PR-time mode produces a git-only diff with no API calls. Merge-time mode applies via API.
Install
python -m pip install anyscale-rtd-redirects
The PyPI distribution is anyscale-rtd-redirects. The installed CLI command is
still rtd-redirects.
For local development, install the package in editable mode:
git clone git@github.com:anyscale/rtd-redirects.git
cd rtd-redirects
python -m pip install -e .[dev]
Release
The package publishes to PyPI as anyscale-rtd-redirects. The command-line
entry point remains rtd-redirects.
Releases are tag-driven. The version comes from the git tag through
setuptools-scm, so the tag is the only thing you bump. There's no version
string to edit in the source. Pushing a v* tag triggers publish.yml, which
runs the tests, builds the distribution, and publishes to PyPI through a Trusted
Publisher (OIDC, no stored token).
The PyPI Trusted Publisher is already configured with these values:
| Field | Value |
|---|---|
| PyPI project | anyscale-rtd-redirects |
| Owner | anyscale |
| Repository | rtd-redirects |
| Workflow | publish.yml |
| Environment | pypi |
To cut a release, complete the following steps. Replace vX.Y.Z with the next
version, for example v0.2.0.
-
Verify the test and package checks locally:
python -m pip install --upgrade -e .[dev] build twine ruff check . pytest python -m build python -m twine check dist/*
-
Create and push a version tag:
git tag vX.Y.Z git push origin vX.Y.Z
-
Confirm the
publishGitHub Actions workflow succeeds. -
Verify the published package from a clean environment:
python -m pip install anyscale-rtd-redirects==X.Y.Z rtd-redirects --help
Quick start
# Auth: token never goes to disk; read from 1Password (or your secret store) into env.
export RTD_API_TOKEN=$(op read "op://Personal/RtD/api-token")
# Optional: avoid passing --project on every call.
export RTD_PROJECT_SLUG=anyscale-ray
# What's in RtD right now?
rtd-redirects list
# Dump the live state to YAML.
rtd-redirects dump --output doc/redirects/current.yaml
# Edit the YAML, then dry-check the diff.
rtd-redirects plan --file doc/redirects/current.yaml
# Apply (interactive — confirms before mutating).
rtd-redirects apply --file doc/redirects/current.yaml
Subcommands
list
Print every redirect currently configured on the RtD project.
rtd-redirects list --project anyscale-ray
dump
Export the RtD project's redirects to a YAML file (or stdout if --output is omitted).
rtd-redirects dump --project anyscale-ray --output doc/redirects/current.yaml
Output is collapsed: records sharing every field except from_url are written as a single multi-source entry with from: as a list.
plan
Compute the diff between your YAML and the RtD project. No mutation.
rtd-redirects plan --project anyscale-ray --file doc/redirects/current.yaml
The output uses + for adds, - for deletes, ~ for updates, @ for position-only reorders, plus a footer counting each phase.
diff-file
Compute the redirect-level diff between two git refs of a YAML file. No RtD API calls — runs entirely from git show. This is the PR-time check engine.
rtd-redirects diff-file --file doc/redirects/current.yaml \
--base origin/master --head HEAD
apply
Apply the YAML to RtD. Confirms interactively unless --yes is set.
# Interactive
rtd-redirects apply --project anyscale-ray --file doc/redirects/current.yaml
# Non-interactive (CI)
rtd-redirects apply --project anyscale-ray --file doc/redirects/current.yaml --yes
Operations run in order: deletes → adds → updates → reorders. Each emits a single audit line to stderr.
audit
Report drift between your YAML and the RtD project, plus ordering / chain validation findings. Exits non-zero on either drift or validation errors so CI can surface them.
rtd-redirects audit --project anyscale-ray --file doc/redirects/current.yaml
validate
Validate ordering and chain risks in one or more YAML files. No RtD credentials required — intended for local use by agents authoring redirects and for pre-commit hooks.
# Single file
rtd-redirects validate doc/redirects/current.yaml
# Several files, each validated on its own (pre-commit passes them this way)
rtd-redirects validate doc/redirects/*.yaml
# Auto-fix ordering errors in place (chains are left for the author)
rtd-redirects validate doc/redirects/current.yaml --fix
# List the per-rule detail for chain notes (info), otherwise summarized
rtd-redirects validate doc/redirects/current.yaml --show-info
Findings come in three severities:
ERROR ordering— rule A's match set is a strict subset of rule B's, but A's position is higher. B fires first; A is unreachable. Lower A's position so it comes before B.--fixreorders deterministically. Errors fail--strictand the pre-commit hook.WARNING chain— rule A'stomatches rule B'sfrom, and B isforce: true. B fires even where A's target exists, so the request chains on every version: a 3xx to A.to, then another to B. Point A'stoat B's destination. Not auto-fixed.INFO chain— rule A'stocould match rule B'sfrom, but B isforce: false, so it fires only where A's target 404s. The request chains only on versions without that page. After a move in newer versions only, that's the expected shape: the existing rule keeps older versions resolving. See Avoid chained redirects. Rules alone can't show which versions have which pages, so runsimulateto check where each URL lands. A:splatmove that a lower-position rule preempts from ever reaching B is alsoinfo, since it can't chain at all. Info findings are summarized as a count;--show-infolists them. They never fail--strict.
Validation is rules-based and decidable in closed form because RtD's pattern surface is intentionally narrow (suffix * only, four redirect types, no embedded wildcards). URL-style types (clean_url_to_html / html_to_clean_url) are excluded since they have no from URL to compare.
Pre-commit integration
This repo ships a .pre-commit-hooks.yaml. Add to your project's .pre-commit-config.yaml:
repos:
- repo: https://github.com/anyscale/rtd-redirects
rev: v0.1.0 # pin to a tag once one is published
hooks:
- id: rtd-redirects-validate
files: ^doc/redirects/.*\.ya?ml$
The hook fails the commit on any ERROR finding. Run pre-commit run rtd-redirects-validate --all-files locally to surface issues before pushing.
rtd-redirects-validate validates each file independently.
--strict on plan / apply
validate is also wired into the project-bound commands for CI use:
# Dry-check ordering during plan
rtd-redirects plan --project anyscale-ray --file doc/redirects/current.yaml --strict
# Refuse to apply if ordering errors exist
rtd-redirects apply --project anyscale-ray --file doc/redirects/current.yaml --strict --yes
audit runs the validator unconditionally and exits non-zero if either drift or validation errors exist (drift is exit 1, validation error is exit 6; validation takes precedence).
Auto-fix caveats
--fix rewrites the YAML using the parsed RedirectSet, which loses comments and authoring formatting (schema_version is preserved). Run --fix, review the diff, and commit. The reordering is deterministic — sorted by (specificity, original position, from_url, type) — so re-running on a clean file is a no-op.
simulate
Replay URLs through the redirect rules before and after a change, on every version in a matrix, and report where each one lands. No RtD credentials required.
validate checks a rule set on its own. A page-rename change can pass it with no errors and still send readers to a landing page, a 404, or a loop, because force: false rules fire only where a page is missing, and which pages are missing differs by version. simulate answers the question a rename PR needs answered: for every old URL, where does it land after this change, in how many hops, and is that the same page it reached before?
rtd-redirects simulate --file doc/redirects/current.yaml --base origin/master --head HEAD \
--pages-before master=inv:https://docs.ray.io/en/master/objects.inv \
--pages-after master=html:doc/_build/html \
--pages latest=inv:https://docs.ray.io/en/latest/objects.inv \
--pages releases-2.40.0=inv:https://docs.ray.io/en/releases-2.40.0/objects.inv \
--prefix /ray-core/ --git-renames doc/source
Rules. --file reads the redirect file at --base for the before side and --head for the after side. --head WORKTREE reads the file on disk. --before-file and --after-file take on-disk files directly instead.
Version matrix. Each version needs a page set before and after the change. --pages VERSION=SOURCE sets both sides; --pages-before and --pages-after override one side. A version the change doesn't touch, such as an older release, uses --pages alone. Include master, latest, and at least one older release: a rule repointed at a moved page's new path is right on master and breaks on every version that doesn't have the move, so a matrix without older releases can't see it. simulate prints a note when the matrix has fewer than three versions.
A page set source is one of the following:
| Source | Reads | Notes |
|---|---|---|
html:DIR |
Every *.html file in a built HTML directory. |
The most faithful source for a local build. |
inv:PATH_OR_URL |
Every std:doc entry in a Sphinx objects.inv. |
Includes build-generated pages. RtD serves one per version, so it's the cheapest faithful source for a published version. |
sitemap:PATH_OR_URL |
Every <loc> in a sitemap.xml, with the host and any /<lang>/<version> prefix stripped. |
|
git:REF:SRCDIR |
Each .md, .rst, or .ipynb file under SRCDIR at REF, mapped to .html. REF may be WORKTREE. |
Cheap, but misses generated pages such as API stubs, which then read as 404s. |
list:PATH |
One path per line. |
Compare like with like on each version. A git tree has no generated pages, so if one side is git: and the other a build, such as inv: or html:, every generated page looks added or removed by the change. simulate prints a note when that happens.
Test URLs. By default simulate tests every rule's from URL on both sides, with wildcards instantiated by a sample page name. --prefix PATH adds every page under PATH in any version's before set; for a directory move, pass the old directory. --url and --urls-file add explicit URLs. A /<lang>/<version>/ URL runs only on that version; a plain path runs on every version. --no-rule-sources turns off the default set.
Judging. For each URL and version, simulate resolves both sides and assigns a verdict:
| Verdict | Meaning | Fails? |
|---|---|---|
regression |
Resolved before, doesn't after: a 404, a loop, or neither. | yes |
wrong-landing |
Resolves on both sides, but after lands somewhere other than the expected page. | yes |
new-loop |
Unresolved before, loops after. | yes |
unmapped |
Resolves on both sides, but the before landing no longer exists and no rename says where it went. | no |
fixed |
Unresolved before, resolves after. | no |
unresolved |
Unresolved on both sides. | no |
unverified |
A redirect jumps to a version outside the matrix. | no |
ok |
Lands on the expected page. | no |
The expected page is the before landing if it still exists after the change. Otherwise it's that landing mapped through the renames. --git-renames SRCDIR derives renames from git renames of Sphinx sources between --base and --head. --rename-map FILE takes a YAML map of old to new page paths, where a key ending in * maps a prefix with :splat:
/ray-core/*: /core/:splat
/core/actors.html: /core/actors/index.html
Renames compose, so the two entries above send /ray-core/actors.html to /core/actors/index.html. Comparison is on the landing version, so a rule that jumps from /en/latest/ to an explicit /en/master/ target is judged against master's pages.
Chains grow with each successive move, because existing rules keep their targets so older versions still resolve. --hop-budget N fails any URL whose after resolution needs more than N redirects. The report always lists URLs that need two or more. --max-hops (default 10) sets when a chain counts as a loop.
Output is a text report per version, or --format json for the per-version counts plus every outcome that isn't a single-hop ok. The exit code is 6 when any URL fails, matching validate.
The resolver models the semantics in Wildcards, Rule ordering, and Robust fan-out: position-based first match, force: false firing only on a 404, page rules matching the path after /<lang>/<version>, exact rules matching the full path, a suffix * with :splat, fragments never matching server-side, and /<lang>/<version>/ targets switching to that version's pages. Disabled rules and the URL-style types are ignored.
YAML schema
A redirect set is one YAML file.
Minimal
schema_version: 1
redirects:
- from: /en/latest/old.html
to: /en/latest/new.html
type: exact
Multi-source
One destination, several sources. Each source becomes its own RtD redirect record.
schema_version: 1
redirects:
- from:
- /en/latest/old1.html
- /en/latest/old2.html
to: /en/latest/new.html
type: exact
Cross-host destination
to: can be any absolute URL — useful for redirecting legacy docs to docs.anyscale.com or blog posts.
schema_version: 1
redirects:
- from: /en/latest/old.html
to: https://docs.anyscale.com/new-thing
type: exact
from: must always be a project path. RtD only intercepts requests for paths it serves; external from URLs are rejected at parse time.
Wildcards (* and :splat)
RtD supports a single suffix wildcard * in from_url, with :splat in to_url substituting the matched portion. Prefix and infix wildcards are not supported by RtD.
schema_version: 1
redirects:
# Bulk redirect every page under one prefix to the same path under another.
- from: /en/releases-2.40.0/*
to: /en/latest/:splat
type: exact
# The same move on every version, firing only where the old path 404s.
- from: /rllib/rllib/*
to: /rllib/:splat
type: page
The tool is a string passthrough for URL fields — * and :splat are stored as-is and interpreted by RtD at request time. Useful for the cohort cutover (legacy version slug → current) and prefix-collapse renames.
page redirects apply across all versions automatically
A page redirect with from: /old.html, to: /new.html triggers on /en/latest/old.html, /en/master/old.html, every legacy version — RtD handles the fan-out itself. To target specific versions instead, write one exact rule per version with a fully-qualified from:
schema_version: 1
redirects:
- from: /old.html # page: every version
to: /new.html
type: page
- from: /en/latest/api.html # exact: latest only
to: /en/latest/api-v2.html
type: exact
Same applies to clean_url_to_html and html_to_clean_url — these describe project-wide URL transitions and don't need from: or to: at all.
schema_version: 1
redirects:
- type: html_to_clean_url # turn /page.html into /page/
Rule ordering: specific before general
RtD picks the first redirect whose from matches the request URL — position-based first-match, not specificity-based. To make a specific rule override a catch-all wildcard, give the specific rule a lower position (or just write it earlier in the YAML; position defaults to entry index).
schema_version: 1
redirects:
# Specific override fires first (position 0).
- from: /en/releases-2.40.0/api/special_case.html
to: /en/latest/api/its_new_home.html
type: exact
# Catch-all wildcard fires for everything else under that version (position 1).
- from: /en/releases-2.40.0/*
to: /en/latest/:splat
type: exact
The tool preserves ordering across dump / parse / apply. diff flags position-only changes as reorder and runs them in a separate pass at apply time so positions settle without churning the data phase.
Inactive versions and slug renames
When you mark a version inactive on RtD, its artifacts are deleted and its URLs start returning 404. Combined with force: false (redirects fire on 404), this means deactivating a version automatically routes its URLs through any matching redirect rule. Your wildcard catch-all picks up all the old paths without any extra work.
Renaming a version slug has the same effect — old-slug URLs return 404, and matching wildcard rules fire. RtD's own docs suggest pairing slug renames with an exact wildcard:
# After renaming releases-2.40.0 -> v2.40.0:
- from: /en/releases-2.40.0/*
to: /en/v2.40.0/:splat
type: exact
(There's a known corner case where an inactive version's HTML can linger in storage and produce an infinite-redirect loop. RtD's infinite-redirect detector returns 404 as a failsafe; worth knowing about if you see one in practice.)
Avoid chained redirects
RtD doesn't promise to resolve chains server-side. If /a → /b and /b → /c are both configured, RtD serves two 3xx responses (the browser follows each hop). When you add a rule, point its to directly at the final destination rather than at another rule's from.
On a versioned project, don't flatten an existing rule when its destination later moves. Say /old → /intermediate exists, and a newer version renames /intermediate to /current. Older versions still serve /intermediate, so the existing rule resolves directly there. Add /intermediate → /current for the newer versions and leave /old → /intermediate alone. Readers of newer versions take two hops, and readers of older versions still land on a page. Rewriting the existing rule to /old → /current sends readers of every version without /current to a 404. Flatten only when the final destination exists in every version where the rule fires, such as on an unversioned project. The validator reports the kept chain as an INFO chain. Run simulate to confirm it lands on a page on every version.
If RtD detects an infinite loop, it returns 404 and stops trying — useful failsafe, but not a substitute for clean authoring.
Robust fan-out: page + force: false + */:splat
RtD's redirect rules default to force: false, which means a redirect only fires when the source URL would otherwise 404. Combined with page (applies across all versions) and a suffix wildcard, you get a single rule that does the right thing on every version without having to enumerate which versions it applies to.
Concrete example — auto-generated API module renamed from old_module to new_module in current docs, but the old name still exists in legacy version archives that you don't want to rebuild:
schema_version: 1
redirects:
- from: /api/old_module/*
to: /api/new_module/:splat
type: page
# force defaults to false: redirect fires only where /api/old_module/... 404s.
What happens at request time:
| Version | /api/old_module/foo.html exists? |
Behavior |
|---|---|---|
latest (after rename) |
no | redirect fires → /api/new_module/foo.html |
v2.55 (rename hasn't happened) |
yes | no redirect, original page renders |
releases-2.40.0 (legacy) |
yes | no redirect, frozen archive intact |
One rule, applied semantically — newer versions get the redirect, older versions keep working. Authoring this with force: true or per-version exact rules would break legacy renders or require N rules across versions.
Use force: true only when you specifically want to override an existing page — e.g., taking over a path that still exists in current docs but should now point elsewhere. Default force: false is almost always what you want for IA cleanup.
Removed in 0.3.0
Two features built for designs that didn't ship were removed in 0.3.0, along with a key that only one of them used. A file that still uses them fails to parse with an error that says how to rewrite it.
-
Multi-version expansion. Top-level
defaults.versionsand per-entryversions:fanned a path-onlyexactrule out across versions. Use a version-lesspagerule instead, which RtD applies on every version and which fires only where the page 404s. See Robust fan-out. When a rule must target specific versions, write oneexactentry per version with a fully-qualifiedfrom, such as/en/latest/old.html. -
Multi-file composition.
plan,apply,audit,diff-file, andsimulatetake a single--file.validate --composedand thertd-redirects-validate-composedpre-commit hook are gone. Merge the files into one, keeping the earlier file's rules first.validatestill accepts several files and checks each on its own. -
The
language_prefix:key. It only fed multi-version expansion, so it had no effect on anything else. Delete it.simulatetakes the prefix as--language-prefix.
Field reference
| YAML field | RtD field | Default | Notes |
|---|---|---|---|
schema_version |
n/a | required | Top-level. Currently 1. |
from |
from_url |
required for page and exact |
String or list. Must be a project path, not external. Optional for clean_url_to_html / html_to_clean_url. |
to |
to_url |
required for page and exact |
String. Path-only, fully-qualified, or external (https://, mailto:, etc.). Optional for clean_url_to_html / html_to_clean_url. |
type |
type |
required | One of page, exact, clean_url_to_html, html_to_clean_url. exact matches the full /<lang>/<version>/... path; the others apply on every version. |
status |
http_status |
301 |
3xx code. |
force |
force |
false |
|
enabled |
enabled |
true |
|
description |
description |
"" |
Operator notes. Surface in PR diff output. |
position |
position |
entry index | Set explicitly only when ordering matters. |
Environment variables
| Variable | Required? | Purpose |
|---|---|---|
RTD_API_TOKEN |
required | Your RtD v3 API token. Never written to disk by the tool; never logged. Read from a secret store at the start of the shell session. |
RTD_PROJECT_SLUG |
optional | Alternative to --project flag. |
RTD_BASE_URL |
optional | API base. Defaults to https://readthedocs.com/api/v3 (Business). Set to https://readthedocs.org/api/v3 for Community. |
Development
git clone git@github.com:anyscale/rtd-redirects.git
cd rtd-redirects
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pytest # 253 tests
ruff check . # lint
Branch naming
doc-XXX-short-description per the Anyscale docs team convention (where DOC-XXX is the Jira ticket key).
PR conventions
- Reference
[DOC-XXX]in the title or summary. - Include a test plan in the body.
- Add or update tests for any module change.
- Run
ruff check .andpytestlocally before pushing.
For broader project intent, architecture, and the deferred-work roadmap, see AGENTS.md.
License
MIT. See LICENSE.
Metadata
Release files for anyscale-rtd-redirects 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| anyscale_rtd_redirects-0.3.0.tar.gz | 95.8 kB | With provenance | Details for anyscale_rtd_redirects-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| anyscale_rtd_redirects-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for anyscale_rtd_redirects-0.3.0-py3-none-any.whl |
Total release size: 150.5 kB
Release files / anyscale_rtd_redirects-0.3.0.tar.gz
| Download URL | anyscale_rtd_redirects-0.3.0.tar.gz |
|---|---|
| Size | 95.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7fd66b70f718f1b9ac34b96f6dbc20c80c3a0b53d3f2ae87b141f0508a562fca
|
|
BLAKE2b-256 checksum How to use checksums |
58f63896580111290c2231e2f8a8c1519376704c7802d7e7d0a9fbcb25352659
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / anyscale_rtd_redirects-0.3.0-py3-none-any.whl
| Download URL | anyscale_rtd_redirects-0.3.0-py3-none-any.whl |
|---|---|
| Size | 54.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bb0a1078fb9cced899a478a79f33697581e68138c79c6ef74e5ce386eba7fb51
|
|
BLAKE2b-256 checksum How to use checksums |
5a40a50bbbed0577c3ebf884bd43b30ad8e962c4dd1cf971aabfb22c700db919
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logSecurity for anyscale-rtd-redirects 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for anyscale_rtd_redirects-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.