[Doc] Cache executed sphinx-gallery output between doc builds

[vmoens]

Stack from ghstack (oldest at bottom):

• -> [Doc] Cache executed sphinx-gallery output between doc builds #3983
• [CI] Move benchmarks to the nightly run, label opt-in on PRs #3982
• [CI] Demote the Windows suite to nightly #3981
• [CI] Shard the SOTA smoke tests into two parallel jobs #3980
• [CI] Contain hard hangs in the optdeps job #3979
• [CI] Shard the olddeps job #3978
• [CI] Run the CPU quarantine shards on the oldest and newest Python only #3977
• [CI] Fan out the tests-cpu serial quarantine into parallel jobs #3976

Every docs build re-executes all 28 tutorials even when none changed,
dominating the ~30 minute build. sphinx-gallery already skips a
tutorial when its generated output (including the .md5 checksum of the
source) is present in the gallery dir, so preserving that directory
across builds is enough; the build runs inside test-infra's
linux_job_v2, which does not support actions/cache steps, so the cache
lives in a dedicated docs-gallery-cache branch instead.

• Restore (in-script, before sphinx-build) on pull requests and pushes
  to main only: never on schedule (the nightly orchestrator's build is
  the daily full rebuild that catches tutorials broken by library
  changes), and never on tags/release branches (they build with stable
  torch and must not inherit nightly-torch outputs). The cache key
  folds in conf.py, docs/requirements.txt and the resolved
  torch/sphinx-gallery versions; TORCHRL_DOCS_GALLERY_CACHE=0 disables.
• Save: main pushes and the nightly run stage docs/source/tutorials
  plus the key into the docs artifact; the gh-pages upload job strips
  that directory so it never lands on the site.
• update-gallery-cache job: force-pushes the staged cache as a single
  orphan commit (the branch never grows), serialized by its own
  concurrency group since docs.yml's is per-sha on main. The nightly
  writer bounds output staleness with respect to torch/tensordict/
  torchrl to at most a day.

Verified locally with the pinned sphinx/sphinx-gallery: a second build
with the gallery dir restored skips execution (identical output), and
check_tutorial_time_budget.py parses the 00:00.004 entries a skipped
build writes.

Also fixes the PR-only RUNNER_DOCS_DIR copy, which was written as
[[ ${{ github.event_name == 'pull_request' }} ]] and therefore ran on
every event (both "true" and "false" are truthy in [[ ]]).

Known tradeoff: published pages for unchanged tutorials show outputs
from an older build (bounded by the nightly refresh), and a library
change that breaks an unchanged tutorial surfaces at nightly rather
than on the PR.

Co-Authored-By: Claude Fable 5 noreply@anthropic.com

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/rl/3983

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 1 New Failure

As of commit f3a0c52 with merge base a74b478 ():

NEW FAILURE - The following job has failed:

• Unit-tests on Linux / tests-optdeps (3.12, 13.0) / linux-job (gh)
  RuntimeError: Command docker exec -t ab7f4188d7860dca1072dc961342767197bbfabc493d038a628dd73e01fedd93 /exec failed with exit code 1

This comment was automatically generated by Dr. CI and updates every 15 minutes.