All jobs

Check for Broken Links in Sphinx Docs with the linkcheck Builder

Yes. An agent adds Sphinx's linkcheck builder to your docs as a tox environment and a weekly workflow, with ignores for what cannot be checked, 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

Sphinx ships a link checker, so the agent's first job is to read how the docs are built and which links the checker would hit. In a project laid out like pallets/click, docs/ holds Markdown pages read by myst_parser, and docs/conf.py turns on sphinx.ext.autodoc, sphinx.ext.extlinks with an issue and a pr role that expand to https://github.com/pallets/click/issues/%s and /pull/%s, sphinx.ext.intersphinx against https://docs.python.org/3/, sphinx_tabs.tabs, sphinxcontrib.log_cabinet and the click theme from pallets_sphinx_themes, with myst_heading_anchors = 3. pyproject.toml keeps the docs tools in a docs dependency group, and [tool.tox.env.docs] builds with sphinx-build -E -W -b dirhtml docs docs/_build/dirhtml, so any warning fails the build. .readthedocs.yaml runs the same -W dirhtml build through uv run --group docs on Ubuntu 24.04 with Python 3.13. uv.lock resolves Sphinx 9.1.0 on Python 3.12 and later, 9.0.4 on 3.11 and 8.1.3 on 3.10.

Then the agent counts what a linkcheck build would request. Across docs/*.md there are 79 external URLs: 29 to github.com, 16 to img.shields.io (the stars and last-commit badges in the project table of docs/contrib.md), 6 to palletsprojects.com, 5 to docs.python.org, and single links to places like diataxis.fr, man7.org and http://docopt.org/. docs/changes.md is one line that includes ../CHANGES.md, and that file carries 599 {issue} and {pr} references, each of which the checker resolves to a GitHub URL and fetches. GitHub rate-limits that many requests; Sphinx honours Retry-After and waits up to linkcheck_rate_limit_timeout, 300 seconds by default, so an unconfigured run is slow before it is useful. docs/commands.md also has http://127.0.0.1:{port}/, a placeholder that is not a URL.

The agent adds the configuration to docs/conf.py: a linkcheck_ignore list for the issue and pull-request URLs the extlinks roles build, for the img.shields.io badges, which are images that change on every request, and for the 127.0.0.1:{port} placeholder; linkcheck_anchors_ignore_for_url for github.com, whose README anchors are rendered by a script and never appear in the fetched HTML; and linkcheck_retries = 2 so one dropped connection does not report a working link as broken. It adds [tool.tox.env.linkcheck] to pyproject.toml with dependency_groups = ["docs"] and sphinx-build -b linkcheck docs docs/_build/linkcheck, which needs no new package because the builder is part of Sphinx. Then it writes .github/workflows/links.yaml: a weekly schedule plus workflow_dispatch, permissions: {}, the same SHA-pinned actions/checkout, astral-sh/setup-uv and actions/setup-python steps as tests.yaml with persist-credentials: false, a run of uv run --locked --no-default-groups --group dev tox run -e linkcheck, and an upload of docs/_build/linkcheck/output.json with the pinned actions/upload-artifact from publish.yaml. zizmor.yaml scans every workflow on push, so the file follows the pins and permissions it enforces.

Before opening anything, the agent runs the checker in its sandbox with uv run --group docs sphinx-build -b linkcheck docs docs/_build/linkcheck, reads output.txt line by line, and sorts what remains into links that are broken, links that redirect to a new canonical page, and links that answer 403 to a non-browser client. A permanent redirect gets the new URL in the Markdown; a page that is gone gets removed or replaced; a host that refuses automated clients goes into linkcheck_ignore with a comment saying why. It then runs tox run -e docs to confirm the -W build still passes, pre-commit run --all-files so ruff-format and codespell accept the edited conf.py, and uvx zizmor .github/workflows/links.yaml on the new workflow.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add external link checking to this Sphinx documentation. Read docs/conf.py, pyproject.toml, .readthedocs.yaml, .pre-commit-config.yaml and every workflow under .github/workflows first, and count the external links in docs/ including anything docs/changes.md includes. Configure the linkcheck builder in docs/conf.py: ignore the GitHub issue and pull request URLs that the extlinks roles generate, the img.shields.io badges and any placeholder URL with braces in it; skip anchor checks for github.com; set a small retry count. Add a tox environment named linkcheck in pyproject.toml that uses the docs dependency group and runs sphinx-build -b linkcheck docs docs/_build/linkcheck. Add .github/workflows/links.yaml on a weekly schedule and workflow_dispatch, with permissions: {}, the same SHA-pinned checkout, setup-uv and setup-python steps as tests.yaml, persist-credentials false, and an artifact upload of docs/_build/linkcheck/output.json. Run the linkcheck build here, fix links that redirect permanently or are gone, add any host that blocks automated requests to the ignore list with a comment, then run tox run -e docs, pre-commit run --all-files and uvx zizmor on the new workflow. Open a pull request with the output.txt summary in its description.",
  "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 and whichever Markdown pages had a link worth fixing, and adds .github/workflows/links.yaml. Its description pastes the end of output.txt, grouped into what was fixed, what was ignored and why, and what is still broken for the maintainers to decide on, with the tox run -e docs and pre-commit results beneath.

On the pull request, the pre-commit workflow checks the formatting of conf.py and zizmor scans the new workflow file. The Tests workflow skips docs/** changes by its paths-ignore, so the docs build itself is proven by the run's record and by Read the Docs, which builds every pull request with the same -W flag.

Before merging, a reviewer reads the ignore list: every pattern there is a link nobody will check again, so each needs a reason in a comment. They also decide whether the weekly schedule is enough or whether the job should also run on pull requests that touch docs/, and whether the linkcheck environment belongs in env_list so tox run with no arguments includes it.

Run it on every Sphinx repository you maintain

A team with several Sphinx projects starts one run per repository from its own server: one POST /o/{org}/sessions each, with this prompt as input, that repository in resources, and a request_id that is a UUID v5 of the repository's full name so a retried call returns the run already started. GET /o/{org}/github lists every repository the Rush GitHub App installation can reach, so the script can pick the ones with a docs/conf.py and no linkcheck environment. Each run reads its own conf.py, so a project whose changelog uses different roles, or that builds with make html instead of tox, gets ignores and a workflow shaped to it.

A team that files documentation work in Linear runs the same prompt from an automation in the Project with a linear trigger on issues labelled docs. The trigger adds the issue after the prompt, so an issue that names a host to skip or asks for the check on every pull request reaches the agent with that detail, and the pull request links back to it.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A linkcheck build is minutes of network traffic against hundreds of hosts, and its value is in reading the output, not in running it. On a laptop the run competes with everything else on the connection and the output scrolls away. In its own sandbox the agent runs it to completion, keeps output.txt and output.json with the run, and the decision behind every ignore pattern is written next to the request that produced it.

The same prompt runs across every documentation repository at once, each in its own sandbox with its own pull request, and the sandbox runs the project's own tooling, so tox, pre-commit and zizmor pass before a maintainer sees the change rather than after.

Frequently asked questions

Will a broken link fail the Read the Docs build?

No. linkcheck is a separate builder with its own output directory, and .readthedocs.yaml keeps running sphinx-build -W -b dirhtml. A dead external link is reported by the weekly job, not by the docs build, which is why the workflow is scheduled rather than attached to the docs tox environment.

Why ignore the GitHub issue and pull request links?

The issue and pr roles in conf.py build every reference in CHANGES.md into a GitHub URL, and that file has 599 of them. Checking each one means hundreds of requests to one host that rate-limits, for links a maintainer typed as a number and that GitHub never removes. Ignoring the pattern keeps the run short and the report about the links that can actually rot.

Does it check the badges in contrib.md?

Sphinx's linkcheck fetches image URLs too, and the stars and last-commit badges from img.shields.io are regenerated on every request. The agent adds that host to linkcheck_ignore; a broken project link in the same table row is still checked through its github.com URL.

Can it run on every pull request instead of weekly?

It can, with a pull_request trigger limited to docs/** and CHANGES.md, but external links fail for reasons unrelated to the change, so a required check would block unrelated work. The agent sets a schedule and workflow_dispatch by default and says in the pull request how to add the pull-request trigger if the team wants it.

What about the intersphinx references to the Python docs?

Those resolve against the inventory sphinx.ext.intersphinx downloads once at build time, not through a request per reference, so they are not part of the linkcheck report. Only explicit URLs in the Markdown, including the ones extlinks roles expand to, are fetched.

More Sphinx jobs

The same job on other stacks

Keep reading