ci: automatically publish docs previews for fork PRs

[jiwenc-nv]

Fork PRs currently require /preview-docs to publish built documentation. Automatically publish previews for PRs changing docs/, with one updated preview-link comment.

The publisher runs trusted default-branch code. Production publishing, maintainer retries, cleanup and GitHub’s fork-build approvals remain unchanged. Same-repository web-client previews remain automatic; maintainers can publish fork web-client previews with /preview-docs.

Validation: 13 tests, full pre-commit, shell checks and read-only GitHub metadata checks passed. Actionlint passes excluding its unsupported existing concurrency.queue key. Live publication requires merging into main. Includes #1273’s notification behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/IsaacCapture/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: cdd18fd3-2a46-4fd9-8c7c-ebd9cdd6a7e7

📥 Commits

Reviewing files that changed from the base of the PR and between 7637a1d and 389cfd1.

📒 Files selected for processing: 6

• .github/scripts/docs_preview.py
• .github/workflows/docs-preview-on-demand.yaml
• .github/workflows/docs.yaml
• .pre-commit-config.yaml
• tests/python/ci/AGENTS.md
• tests/python/ci/test_docs_preview.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

📝 Walkthrough

The docs workflow now builds pull-request artifacts without deploying previews. A new selector validates workflow-run and /preview-docs events, pull requests, changed files, and artifacts. The preview workflow uses the selected artifacts, checks the pull request head before publishing, and posts or updates a preview comment. Unit tests and a pre-commit hook cover preview selection.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DocsWorkflow
  participant IssueComment
  participant PreviewWorkflow
  participant docs_preview.py
  participant GitHubAPI
  participant ArtifactStorage
  participant GitHubPages
  DocsWorkflow->>PreviewWorkflow: successful docs workflow completion
  IssueComment->>PreviewWorkflow: /preview-docs comment
  PreviewWorkflow->>docs_preview.py: event metadata
  docs_preview.py->>GitHubAPI: validate run, pull request, and artifacts
  GitHubAPI-->>docs_preview.py: matching pull request and artifact IDs
  docs_preview.py-->>PreviewWorkflow: publish metadata
  PreviewWorkflow->>ArtifactStorage: download selected artifacts
  PreviewWorkflow->>GitHubAPI: recheck pull request head
  PreviewWorkflow->>GitHubPages: publish preview

Loading

Merge Risk: ⚪ Minimal · up to 389cf

This change moves docs preview publishing for fork and same-repository PRs into a guarded default-branch workflow. No concrete merge-blocking risk was found. The workflow can only be exercised end to end after it merges.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 2 files. (4 skipped: 4…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: automatic documentation preview publication for fork pull requests.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 2 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[ivany-nv]

Legend: 🚫 BLOCKER = merge-blocking | 💡 SUGGESTION = meaningful improvement | 🧹 NIT = precise small correction

	Finding
🚫	.github/scripts/docs_preview.py:79-89 - commits/{sha}/pulls returns nothing for open fork PRs: none of the 13 open fork PRs came back (all 10 same-repo PRs sampled did), so select_preview() returns None for docs-changing forks like #1252 and #1253 whose docs builds succeeded at their current head. Fork PRs therefore never auto-publish, and the greeting comment that pointed their authors at /preview-docs is deleted. Look the PR up with pulls?state=open&head=<head_repository.owner.login>:<head_branch> instead and keep the matches() checks; with that change alone, both PRs are selected correctly. The tests miss this because the fake API at test_docs_preview.py:62-64 answers the commit lookup.
🚫	.github/workflows/docs-preview.yaml:138-139 - gh api refuses --slurp combined with --jq (gh v2.102.0: "the --slurp option is not supported with --jq or --template"; older gh has no --slurp), so under set -e this step exits right after Deploy preview to gh-pages has pushed. Every successful preview then gets no PR comment and no summary line, the run ends red, and a /preview-docs gets 👎 for a preview that did deploy. Pipe the slurped output into standalone jq -r instead, as the recheck step at L108 already does; #1273 used --paginate --jq without --slurp.
💡	.github/scripts/docs_preview.py:101-106 - PRs that change only the web client lose their preview. The automatic path requires a docs/ file and both paths require a docs-html artifact (L116-119), which a client-only build never produces, so /preview-docs on such a PR does nothing and leaves no reaction. On main, same-repo client-only PRs publish preview/pr-<N>/client/ (base docs.yaml:256-260), and #1063 and #1148 have live previews of exactly that kind. Accept a lone webapp artifact (at least for same-repo PRs and /preview-docs, making the index.html check at docs-preview.yaml:92 conditional), or say in the PR body that web-client previews are being dropped.
💡	docs/source/development/contributing.rst:43-73 - The contributor guide still describes the old flow: the same-repo preview URL in the Build & deploy docs Summary tab, a bot comment when a fork PR opens, and fork previews needing a maintainer's /preview-docs. This PR removes all three, so update the section to cover automatic publication for docs-changing PRs, the single updated preview comment, and /preview-docs as a maintainer retry.
🧹	none

[jiwenc-nv]

@ivany-nv Addressed all four findings in 73d47d0:

• Find open PRs by URL-encoded source owner/branch, retaining repository, branch, SHA, state, and ambiguity checks.
• Pipe paginated/slurped comments into standalone jq.
• Preserve automatic same-repository web-client previews and maintainer-triggered fork web-client previews. Webapp-only publication links to /client/; automatic docs publication still requires docs changes.
• Update the contributor guide for automatic fork docs previews, the updated preview comment, maintainer retries, and cleanup.

Validation: 13 tests, full pre-commit, docs build, and artifact staging for docs-only/webapp-only/combined outputs passed. Actionlint passes with the existing unsupported concurrency.queue exception. The corrected comment query succeeds against GitHub. Read-only selection now accepts fork PRs #1252/#1253 and web-client PRs #1063/#1148; this check maps the renamed workflow lookup to its current pre-merge API path. End-to-end automatic publication remains pending installation on main.

[jiwenc-nv]

Consolidated into #1273 at the author’s request. Its branch now contains the complete implementation, diagram, and all review fixes from this PR, with identical file contents. Please continue review on #1273.