Make gallery docs resilient to dataset outages

[snesmaeili]

Summary

• keep normal local documentation builds executing the complete gallery
• make GitHub Actions use an explicit offline policy that renders, but does not execute, the 13 examples that download external datasets
• audit the external-data list in unit tests and reject gallery scripts that can terminate Sphinx with sys.exit
• replace two false-success sys.exit(0) paths with contextual failures for requested full-data builds
• fix the previously masked broken RST citation target

Root cause

The documentation job depended on the external NoiseTools host, which currently returns HTTP 503. In addition, two EEGBCI examples caught download failures and called sys.exit(0), allowing the entire Sphinx process to stop early with a success status. This could produce an incomplete documentation artifact while CI appeared green.

Sphinx-Gallery's filename_pattern controls execution without removing source pages. CI now opts into a reviewed deny list through MNE_DENOISE_DOCS_EXECUTE_EXTERNAL_DATA=false; the environment variable remains unset by default, so local builds retain full execution.

Validation

• Python 3.10: pytest tests/test_docs_gallery.py -q (2 passed)
• Python 3.12: pytest tests/test_docs_gallery.py -q (2 passed)
• pre-commit run --all-files (all hooks passed)
• clean offline Sphinx build: python -m sphinx -M html . _build-ci -W --keep-going
  • reached the normal build succeeded terminal state
  • executed 21/21 offline-safe gallery scripts
  • rendered all 13 external-data pages as source
  • produced 559 files / 23,972,109 bytes
  • downloaded no NoiseTools files

Scope

This changes documentation execution policy and example failure reporting only. It does not replace scientific datasets, inject synthetic stand-ins, or change denoising method behavior.

[snesmaeili]

Traceability: this draft addresses the external-data documentation failures observed while validating draft PRs #42, #46, #49, #50, #51, #55, #58, #59, and #61. Their method/lint/coverage jobs are independent of this fix; no PR is being merged or marked ready as part of this work.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.09%. Comparing base (e84d8d0) to head (87ed9d0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #62      +/-   ##
==========================================
+ Coverage   96.08%   96.09%   +0.01%     
==========================================
  Files          65       65              
  Lines        8170     8170              
  Branches     1420     1420              
==========================================
+ Hits         7850     7851       +1     
  Misses        152      152              
+ Partials      168      167       -1     

Flag	Coverage Δ
unittests	96.09% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
mne_denoise/dss/denoisers/temporal.py	100.00% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.