[docs] Improve documentation CI and integrity checks

[wheresmyhair]

Summary

This PR improves LMFlow's documentation CI by introducing targeted documentation integrity checks, cleaning up existing Sphinx warnings (by modifying various docstrings), and restoring the repository's gh-pages branch deployment workflow.

The CI now records all Sphinx warnings but only blocks pull requests when warnings indicate broken internal references or documentation navigation.

Future CI behaviors

PRs

PR will:

1. Install the documentation dependencies.
2. Build the Sphinx HTML documentation.
3. Record all Sphinx warnings.
4. Run the targeted internal-reference and navigation checker.
5. Fail if a structural documentation problem is detected.
6. Skip artifact upload and Pages deployment.

Pushes to main

Successful main builds will:

1. Build and validate the documentation.
2. Upload the generated HTML as an intermediate artifact.
3. Download the artifact in a separate deployment job.
4. Publish the HTML to the gh-pages branch.

Testing

Following checks were completed locally:

• Sphinx HTML build:
  • sphinx-build -b html -w _build/sphinx-warnings.log docs/source _build/html
  • Result: successful build with an empty warning log.
• Documentation integrity checker:
  • python .github/scripts/check_doc_links.py _build/sphinx-warnings.log
  • Result: passed.
• Historical warning-log regression test:
  • Correctly detected broken MyST references and documents missing from the toctree.
• Synthetic warning classification:
  • Missing internal references and toctree warnings were blocking.
  • Non-structural formatting warnings were non-blocking.
• Ruff:
  • ruff check .github/scripts/check_doc_links.py --select E4,E7,E9,F --ignore E731
  • Result: passed.
• Git diff validation:
  • git diff --check
  • Result: passed.

Impact

• Documentation links and navigation are protected by CI.
• Non-structural Sphinx warnings remain observable without unnecessarily blocking contributors.
• GitHub Pages continues to deploy through the repository's existing gh-pages branch model.
• No runtime APIs, CLI arguments, training behavior, or dataset formats are changed.
• No GitHub repository setting changes are required.

[wheresmyhair]

Note: the CI / CPU unit tests (Python 3.9) (pull_request) fail should be fixed once #975 has been merged.

[wheresmyhair]

Patch:

1. Restrict GitHub Pages deployment to the official LMFlow repository’s main branch, preventing forks and mirrors from deploying.
2. Install CPU-only PyTorch in unit-test CI to avoid exhausting runner disk space with CUDA dependencies.

[wheresmyhair]

Patch 2:
Restrict doc builds to the upstream LMFlow repo (checks for PRs targeting main still works).