fix: prevent gh-pages repo bloat from doc preview artifacts (#1309)

### What does this PR do?

Type of change: Bug fix

Fixes gh-pages branch bloat that grew from ~26 MB to ~441 MB in four
weeks (nvbug 6099503). Three compounding causes were identified and
addressed:

1. **Sphinx `.doctrees/` cache published to gh-pages** — `sphinx-build`
was writing its build cache inside `build/html/` which was then uploaded
verbatim. Accounts for ~3.3 GB uncompressed across history.
2. **`JamesIves/github-pages-deploy-action` appending a commit on every
push** — main-site files accumulated forever with `single-commit: false`
(default).
3. **PR preview deploying on every `synchronize` event for all PRs** —
`rossjrw/pr-preview-action` re-deployed the full site for every push to
any PR regardless of whether docs changed (e.g. PR #1128 triggered 64
preview deploys × ~11 MB each).

Changes:
- Pass `-d /tmp/doctrees` to `sphinx-build` so `.doctrees/` is never
written into `build/html/`
- Add `paths: [docs/**, modelopt/**]` filter to `pull_request` trigger
so the docs workflow only runs on PRs that touch docs or source code
- Set `single-commit: true` on the deploy action so main-site pushes
squash into one commit
- Deduplicate docs build: `deploy-preview` now downloads the artifact
from `build-docs` instead of running a second `sphinx-build`
- Set `retention-days: 1` on the artifact since it is only needed for
the duration of the workflow run

The one-time cleanup (force-push squashed orphan to gh-pages) was
already applied separately — repo is now ~59 MB for a full clone vs ~441
MB before.

### Usage

N/A — CI/workflow change only.

### Testing

- Workflow logic reviewed manually.
- The one-time cleanup was verified: `git rev-list --objects
--disk-usage origin/gh-pages` now reports ~28 MB; full clone is ~59 MB.

### Before your PR is "*Ready for review*"

- Is this change backward compatible?: ✅
- If you copied code from any other sources or added a new PIP
dependency, did you follow guidance in `CONTRIBUTING.md`: N/A
- Did you write any new necessary tests?: N/A
- Did you update
[Changelog](https://github.com/NVIDIA/Model-Optimizer/blob/main/CHANGELOG.rst)?:
N/A

### Additional Information

nvbug 6099503

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Chores**
* Optimized documentation build and deployment workflow in CI/CD
pipeline.
* Improved pull request documentation preview handling with faster build
timeouts and refined artifact management.
* Enhanced GitHub Pages deployment configuration for better consistency.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Keval Morabia <28916987+kevalmorabia97@users.noreply.github.com>
Signed-off-by: Grzegorz Karch <gkarch@nvidia.com>

Author: kevalmorabia97

.github/workflows/pages.yml

@@ -23,33 +23,55 @@ permissions:
 
 jobs:
   build-docs:
+    if: github.event.action != 'closed'
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
       - uses: ./.github/actions/ubuntu-setup
       - name: Build docs
         run: pip install nox uv && nox -s docs
       - name: Upload docs artifact
-        if: github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-artifact@v4
         with:
           name: docs-html
           path: docs/build/html
+          retention-days: 1
+
+  changes:
+    if: github.event_name == 'pull_request' && github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - 'modelopt/**'
+              - '.github/workflows/pages.yml'
 
   deploy-preview:
-    if: github.event_name == 'pull_request'
+    if: |
+      always() &&
+      github.event_name == 'pull_request' &&
+      (github.event.action == 'closed' || needs.changes.outputs.docs == 'true')
+    needs: [build-docs, changes]
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 10
     # Per-PR concurrency without cancel-in-progress so 'closed' cleanup always runs
     concurrency:
       group: pr-preview-${{ github.event.pull_request.number }}
     steps:
       - uses: actions/checkout@v6
-      - uses: ./.github/actions/ubuntu-setup
-      - name: Build docs
+      - name: Download docs artifact
         if: github.event.action != 'closed'
-        run: pip install nox uv && nox -s docs
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/html
       - name: Deploy / remove PR preview
         uses: rossjrw/pr-preview-action@v1
         with:
@@ -70,5 +92,6 @@ jobs:
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: docs/build/html
+          single-commit: true
           # Preserve PR preview subdirectories deployed by the deploy-preview job
           clean-exclude: pr-preview

noxfile.py

@@ -164,6 +164,8 @@ def docs(session):
     with session.chdir("docs"):
         session.run(
             "sphinx-build",
+            "-d",
+            "/tmp/doctrees",
             "source",
             "build/html",
             "--fail-on-warning",