docs: fix docs preview

[jiwenc-nv]

ci: deploy fork-PR previews via /preview-docs slash command

Reverts 274ca8e (the workflow_run-based preview that was permanently blocked by environment deployment-branch protection on docs-preview) and replaces it with a slash-command flow that doesn't need the env at all.

Summary

• Auto-preview restored for canonical pushes and same-repo PRs — docs.yaml deploys to nvidia.github.io/IsaacTeleop/preview/pr-<N>/ on every push, same as pre-274ca8e.
• Fork PRs no longer 403 — docs.yaml builds the artifacts (docs build is still validated) but the deploy step is gated on head.repo.full_name == github.repository.
• New docs-preview-on-demand.yaml handles fork PRs via two triggers:
  • pull_request_target: opened — bot posts instructional comment.
  • issue_comment: created containing /preview-docs — verifies the commenter has write+ access, then downloads the matching docs.yaml artifacts for that PR's head SHA and pushes them to preview/pr-<N>/. Reacts 👀 → 👍 on the comment and posts a follow-up with the URL.
• No PR code execution in the slash-command path. The deploy is a pure artifact passthrough — pip install / npm install / Sphinx all run in the original docs.yaml job, and /preview-docs just static-deploys what came out.
• New composite action .github/actions/build-cloudxr-web-client/ encapsulates the NGC SDK download + npm build, used by docs.yaml.
• contributing.rst documents the canonical/fork split and the /preview-docs flow.

Summary by CodeRabbit

• New Features

  • Introduced on-demand documentation preview capability triggered via pull request comments, enabling contributors and maintainers to generate and review documentation changes before merge.

• Documentation

  • Updated contributing guide with detailed local documentation build instructions and comprehensive guidance on GitHub Pages preview deployment workflows for both internal and forked pull requests.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2b459684-c81c-4060-94d6-469b025aa328

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request introduces a new composite GitHub Action for building the CloudXR web client and refactors documentation deployment workflows. A new on-demand preview workflow is added with permission checks to allow maintainers to manually trigger docs previews for fork PRs. The main docs workflow is updated to use the new composite action and no longer automatically deploys PR previews; the docs-deploy-preview workflow is removed. Contributing documentation is expanded with instructions for local docs verification and GitHub Pages preview usage.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant GitHub as GitHub UI
    participant Workflow as On-Demand Workflow
    participant PermCheck as Permission Check
    participant ArtifactStore as Artifact Storage
    participant GHPages as gh-pages Deployment
    participant PR as PR Comments

    User->>GitHub: Comment /preview-docs on PR
    GitHub->>Workflow: Trigger workflow_dispatch via comment
    
    Workflow->>PermCheck: Verify commenter permissions
    alt Fork PR
        PermCheck->>PR: React -1, post comment
        PermCheck->>Workflow: Fail (insufficient permissions)
    else Authorized
        Workflow->>GitHub: React eyes emoji
        Workflow->>ArtifactStore: Fetch PR head SHA
        Workflow->>Workflow: Find latest successful docs.yaml run
        alt Build artifact found
            Workflow->>ArtifactStore: Download docs-html + webapp
            Workflow->>GHPages: Deploy to preview/pr-{N}/
            Workflow->>PR: React +1, post preview URL
        else No build found
            Workflow->>PR: React -1, post error comment
            Workflow->>Workflow: Fail
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: fix docs preview' is vague and does not clearly convey the substantial architectural changes made to the docs preview system.	Consider a more descriptive title that reflects the key change, such as 'docs: replace workflow-based preview with slash-command flow for fork PR support' or 'docs: add on-demand preview workflow for fork PRs'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[jiwenc-nv]

I have been testing this locally with my own fork. here is an example: jiwenc-nv#3

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/actions/build-cloudxr-web-client/action.yml:
- Around line 30-34: The sdk-version step currently assigns version via grep but
doesn't validate results; update the id "sdk-version" step to check that the env
file contains a non-empty CXR_WEB_SDK_VERSION and fail fast if not: after
extracting into variable "version" (from the grep/cut pipeline), test that
version is non-empty, emit a clear error message referencing CXR_WEB_SDK_VERSION
and exit with a non-zero status so the workflow stops (instead of writing an
empty "version" to GITHUB_OUTPUT), ensuring downstream curl/download steps never
receive a malformed URL.

In @.github/workflows/docs-preview-on-demand.yaml:
- Around line 156-162: The workflow step named "Deploy preview to gh-pages" is
still using peaceiris/actions-gh-pages@v3 which can cause runner compatibility
failures; update the uses reference to peaceiris/actions-gh-pages@v4 in that
step (keep existing inputs: github_token, publish_dir, destination_dir,
keep_files) and verify the action input names remain compatible after the bump
(adjust if v4 renamed any inputs).

In @.github/workflows/docs.yaml:
- Around line 153-157: Update the GitHub Action usage from
peaceiris/actions-gh-pages@v3 to peaceiris/actions-gh-pages@v4 and, because v4
requires a newer Node runtime, add the environment variable
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true to the workflow job (or otherwise set
the appropriate node runtime) to avoid the deprecated Node issue; ensure the
uses line is changed to the v4 tag and that the job/env block includes
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true so the action runs on Node 24 until a v5
or different long-term solution is adopted.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 07a9211e-4ab4-43d2-b3af-bb5e089a82be

📥 Commits

Reviewing files that changed from the base of the PR and between 48011b6 and 8821bdf.

📒 Files selected for processing (5)

• .github/actions/build-cloudxr-web-client/action.yml
• .github/workflows/docs-deploy-preview.yaml
• .github/workflows/docs-preview-on-demand.yaml
• .github/workflows/docs.yaml
• docs/source/getting_started/contributing.rst

💤 Files with no reviewable changes (1)

• .github/workflows/docs-deploy-preview.yaml