Stop Reviewing Docs by Diff: Use Read the Docs Pull Request Previews

Reviewing a documentation pull request by reading a Markdown or reStructuredText diff is slow and error prone. You can see a changed heading or a new admonition in source, but you cannot judge layout, cross-reference resolution, or code block rendering from the diff alone. Pull request preview builds on Read the Docs solve this by building the docs for the PR branch and posting a temporary rendered URL as a status check.

The useful takeaway is to treat documentation builds like tests: require the preview build to pass before merge. This ensures that visual regressions or broken internal links are caught before they ever reach the default branch.

The Limitation of Source-Based Review

Source control diffs are designed for tracking logic changes in code, but they are poor for layout. If you update a complex Sphinx table or a nested admonition, the diff shows you the raw syntax change. It doesn't show you if the table overflows the container, whether an image path resolves, or how a code block renders with your theme.

Preview builds shift the review question from "is the syntax correct?" to "does the documentation work?" Reviewers can comment on the actual rendered HTML, checking layout, admonitions, and navigation flow that are invisible in a raw text file.

How Preview Builds Work

Read the Docs can trigger a dedicated build pipeline whenever a pull request is opened. It uses the same .readthedocs.yaml configuration as your production environment, so a build that passes in the preview should behave the same way in production.

Once the build completes, Read the Docs posts a status check directly to the PR with a link to the rendered preview. That preview is temporary and clearly marked as non-production; it is not indexed into the stable version listing, so it won't pollute your search results or version selector.

A side benefit: because preview builds run the real pipeline, they surface build failures early. A broken cross-reference, missing dependency, or invalid config fails the PR check before it reaches the default branch.

Configuration and Workflow

To enable this, turn on the pull request builds option in your project settings on Read the Docs. For projects using Sphinx or MkDocs, it works with your existing build configuration.

Here is an example of a typical .readthedocs.yaml file for a Sphinx project, which the preview engine will also use:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: docs/requirements.txt

Once enabled, the practical engineering decision is to configure your repository's branch protection rules to require the docs status check to pass before merge. This treats documentation regressions with the same rigor as failing tests, preventing a broken cross-reference or missing dependency from reaching your main branch.

Trade-offs and Cautions

Preview builds are highly effective, but there are two constraints to consider:

• Build minutes: Every PR consumes build minutes. High-activity repositories with frequent open PRs can burn through plan limits quickly, so watch your usage.
• Security: Builds for pull requests from external forks may be limited or disabled depending on project configuration, since building untrusted code has security implications. Check your project's settings if fork PRs aren't triggering previews.

Feature names, availability tiers, and configuration options change over time, so confirm the details against the current Read the Docs documentation before rolling this out.

Verifying the Setup

To confirm everything works, open a test PR and check that the preview link appears as a status check. Then intentionally introduce a broken cross-reference (for example, a Sphinx reference to a nonexistent target). If the preview build fails and the PR check reports the failure, your workflow is correctly configured. You can also check the project's build history page to confirm preview builds are listed separately from version builds.

Once the check is required for merge, documentation quality stops depending on reviewers mentally rendering diffs — and starts depending on the same kind of automated gate you already trust for code.