Skip to content

Docs previews for source repository pull requests #2

Open

Description

@pimlock

Problem

Docs changes in a source repository (NVIDIA/OpenShell, ai-openshell/sdk-go, ...) can't be seen on the site until they merge, and problems surface only in this repository's build. The full site build treats broken links in fetched versions as warnings, so a source repository needs its own check that fails its pull request when it breaks its docs or a page another repository links to.

Proposal

Ship pull request previews as a reusable workflow that source repositories call:

  • Build only the calling repository's docs with this repository's theme and assembler. Everything about the other repositories comes from the live site's links.json.
  • Publish each preview to the calling repository's gh-pages branch under pr-<n>/, and link it from one pull request comment that is updated on every run. Closing the pull request removes the preview.
  • Treat broken links as errors, and fail when a page or heading that another repository links to disappears, unless docset.yml lists it under redirects:.
  • Also build pr-<n>/diff/ for every preview, which marks what the pull request changed on each page. The branch below still gates it behind a docs-diff label; drop the label when shipping.

The implementation was removed from the initial setup (#1) to keep it small. It is kept on branch feat/2-pr-previews/pimlock, one commit on top of #1, ready to rebase once #1 merges.

Open questions

  • This repository is private. Other repositories can call its reusable workflow and check it out only if it is public, or if the organization allows access from private repositories.
  • Previews of pull requests from forks can't publish or comment, because their token is read-only.
  • GitHub Pages must be enabled on each calling repository.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions