[TRTLLM-16185][infra] route documentation changes to docs and CPU validation

jenkins/scripts/cbts/README.md

@@ -44,12 +44,13 @@ Ten rules, registered in `main.py::RULE_CLASSES`:
 | `WaivesRule` | `waiveonly` | `tests/integration/test_lists/waives.txt` |
 | `TestsDefRule` | `testdefonly` | `tests/**/*` (.py via AST; data files via dir walk-up) |
 | `TestListRule` | `testlistonly` | `tests/integration/test_lists/test-db/*.yml` |
-| `VisualGenRule` | `visualgenonly` | `examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`, `tensorrt_llm/media/**`, `tensorrt_llm/visual_gen/**` (excl. `.md`; reference images such as `cat_piano.png` ARE test fixtures and stay claimed; outward-facing files force fallback) |
-| `SpecDecRule` | `specdeconly` | `tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py` (excl. `.md`; other suffixes incl. images kept as potential test fixtures) |
-| `ModelingV2Rule` | `modelingv2only` | `tensorrt_llm/_torch/_experimental/modeling_v2/**` (excl. `.md`) |
-| `AgentFlowRule` | `agentflowonly` | `agent-flow/**` (excl. `.md`) |
-| `OpenEngineRule` | `openengineonly` | `tensorrt_llm/grpc/openengine/**` (excl. `.md`) |
-| `OutOfScopeRule` | `noop` | QA / dev test lists, `.test_durations`, `microbenchmarks/`, `**/*.md` (image suffixes intentionally not claimed — image fixtures cannot be distinguished from doc diagrams by location, so image edits fall back to baseline) |
+| `VisualGenRule` | `visualgenonly` | `examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`, `tensorrt_llm/media/**`, `tensorrt_llm/visual_gen/**` (excl. docs; reference images such as `cat_piano.png` ARE test fixtures and stay claimed; outward-facing files force fallback) |
+| `SpecDecRule` | `specdeconly` | `tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py` (excl. docs; other suffixes incl. images kept as potential test fixtures) |
+| `ModelingV2Rule` | `modelingv2only` | `tensorrt_llm/_torch/_experimental/modeling_v2/**` (excl. docs) |
+| `AgentFlowRule` | `agentflowonly` | `agent-flow/**` (excl. docs) |
+| `OpenEngineRule` | `openengineonly` | `tensorrt_llm/grpc/openengine/**` (excl. docs) |
+| `DocsRule` | `docsonly` | `docs/**` → `CPU-Build_Docs` plus complete `l0_cpu`; other `**/*.md` / `**/*.rst` → `CPU-Build_Docs` only |
+| `OutOfScopeRule` | `noop` | `.github/CODEOWNERS`, QA / dev test lists, `.test_durations`, `microbenchmarks/` (image suffixes intentionally not claimed — image fixtures cannot be distinguished from doc diagrams by location, so image edits fall back to baseline) |
 
 See `rules/README.md` for per-rule logic.
 
@@ -60,13 +61,14 @@ See `rules/README.md` for per-rule logic.
 | `waiveonly` | `WaivesRule` fired solo: PR only edits `waives.txt`. |
 | `testdefonly` | `TestsDefRule` fired solo: PR only edits files under `tests/**/*`. |
 | `testlistonly` | `TestListRule` fired solo: PR only adds entries under `tests/integration/test_lists/test-db/*.yml`. |
-| `visualgenonly` | `VisualGenRule` fired solo: PR only touches VisualGen internal source paths (`examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`; excl. `.md`; image fixtures like `cat_piano.png` are claimed). Narrows to blocks containing VG test entries. Outward-facing files under `tensorrt_llm/visual_gen/**` and `tensorrt_llm/media/**` (eagerly imported by `trtllm-serve`) force `null` fallback. |
-| `specdeconly` | `SpecDecRule` fired solo: PR only touches speculative-decoding source paths (`tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py`; excl. `.md`). Narrows to blocks containing spec-dec test entries (eagle / medusa / redrafter / ngram / draft-target-model / MTP). |
-| `modelingv2only` | `ModelingV2Rule` fired solo: PR only touches the modeling_v2 subtree (`tensorrt_llm/_torch/_experimental/modeling_v2/**`; excl. `.md`, which is a fifth of the subtree — every catalog entry carries a contract document). Narrows to blocks containing modeling_v2 test entries (`unittest/_torch/modeling_v2/`, `test_modeling_v2_*`). No outward-facing fallback is needed: nothing imports the subtree unless `TRTLLM_MODELING_V2` is set, and its one caller outside the subtree (`_torch/models/modeling_auto.py`) is left unclaimed, so touching the shared resolver falls back to baseline. |
-| `agentflowonly` | `AgentFlowRule` fired solo: PR only touches `agent-flow/**` source or test files (excl. `.md`). Runs `CPU-AgentFlow-UnitTest`. |
-| `openengineonly` | `OpenEngineRule` fired solo: PR only touches `tensorrt_llm/grpc/openengine/**` source files (excl. `.md`). Narrows to the registered OpenEngine unit tests: the stub-based ones on the always-run `CPU-Generic-*` stages, plus `test_capability_conformance.py` on `A10-PyTorch-*`, which needs a GPU. |
-| `testsonly` | Multiple rules from the testsonly family fired (`waiveonly`, `testdefonly`, `testlistonly`, `visualgenonly`, `specdeconly`, `modelingv2only`, `agentflowonly`, `openengineonly`); their narrows union. |
-| `noop` | Rule(s) fired but determined no test stages need to run (QA-only path, removals-only test list, all-miss waives, in-namespace .py with no covering YAML entry, docs-only edits). Layer 2 still applies. |
+| `visualgenonly` | `VisualGenRule` fired solo: PR only touches VisualGen internal source paths (`examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`; excl. docs; image fixtures like `cat_piano.png` are claimed). Narrows to blocks containing VG test entries. Outward-facing files under `tensorrt_llm/visual_gen/**` and `tensorrt_llm/media/**` (eagerly imported by `trtllm-serve`) force `null` fallback. |
+| `specdeconly` | `SpecDecRule` fired solo: PR only touches speculative-decoding source paths (`tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py`; excl. docs). Narrows to blocks containing spec-dec test entries (eagle / medusa / redrafter / ngram / draft-target-model / MTP). |
+| `modelingv2only` | `ModelingV2Rule` fired solo: PR only touches the modeling_v2 subtree (`tensorrt_llm/_torch/_experimental/modeling_v2/**`; excl. docs, which are a fifth of the subtree — every catalog entry carries a contract document). Narrows to blocks containing modeling_v2 test entries (`unittest/_torch/modeling_v2/`, `test_modeling_v2_*`). No outward-facing fallback is needed: nothing imports the subtree unless `TRTLLM_MODELING_V2` is set, and its one caller outside the subtree (`_torch/models/modeling_auto.py`) is left unclaimed, so touching the shared resolver falls back to baseline. |
+| `agentflowonly` | `AgentFlowRule` fired solo: PR only touches `agent-flow/**` source or test files (excl. docs). Runs `CPU-AgentFlow-UnitTest`. |
+| `openengineonly` | `OpenEngineRule` fired solo: PR only touches `tensorrt_llm/grpc/openengine/**` source files (excl. docs). Narrows to the registered OpenEngine unit tests: the stub-based ones on the always-run `CPU-Generic-*` stages, plus `test_capability_conformance.py` on `A10-PyTorch-*`, which needs a GPU. |
+| `docsonly` | `DocsRule` fired solo: all documentation changes run `CPU-Build_Docs`; changes under `docs/**` also run the complete `l0_cpu` suite on matching `CPU-Generic-*` stages. Docs-only orchestration skips the SBSA track, so its resolved ARM stage is not launched. |
+| `testsonly` | Multiple rules from the testsonly family fired (`waiveonly`, `testdefonly`, `testlistonly`, `visualgenonly`, `specdeconly`, `modelingv2only`, `agentflowonly`, `openengineonly`, `docsonly`); their narrows union. |
+| `noop` | Rule(s) fired but determined no test stages need to run (QA-only path, removals-only test list, all-miss waives, in-namespace .py with no covering YAML entry). Layer 2 still applies. |
 | `null` (fallback) | A rule cannot decide, scopes don't combine, or there are unhandled files. Groovy defers to baseline filter chain. |
 
 `_combine_scopes` (main.py): rules with `scope="noop"` give way to any
@@ -90,10 +92,12 @@ jenkins/scripts/cbts/
 │   ├── base.py            Rule ABC + PRInputs + RuleResult
 │   ├── _helpers.py        diff iteration + lookup-into-block_filters + stages_by_yaml_stem
 │   ├── waives_rule.py
+│   ├── docs_rule.py
 │   ├── tests_def_rule.py
 │   ├── test_list_rule.py
 │   ├── visual_gen_rule.py
 │   ├── spec_dec_rule.py
+│   ├── modeling_v2_rule.py
 │   ├── agent_flow_rule.py
 │   ├── openengine_rule.py
 │   └── out_of_scope_rule.py

jenkins/scripts/cbts/main.py

@@ -62,6 +62,7 @@
 from rules._helpers import strip_noop_diff_lines  # noqa: E402
 from rules.agent_flow_rule import AgentFlowRule  # noqa: E402
 from rules.base import PRInputs, Rule, RuleResult, format_reason  # noqa: E402
+from rules.docs_rule import DocsRule  # noqa: E402
 from rules.modeling_v2_rule import ModelingV2Rule  # noqa: E402
 from rules.openengine_rule import OpenEngineRule  # noqa: E402
 from rules.out_of_scope_rule import OutOfScopeRule  # noqa: E402
@@ -86,6 +87,7 @@
     ModelingV2Rule,
     AgentFlowRule,
     OpenEngineRule,
+    DocsRule,
     OutOfScopeRule,
 ]
 
@@ -104,6 +106,7 @@ def build_rules(
         ModelingV2Rule(yaml_index, stages),
         AgentFlowRule(yaml_index, stages),
         OpenEngineRule(yaml_index, stages),
+        DocsRule(yaml_index, stages),
         OutOfScopeRule(yaml_index, stages),
     ]
 
@@ -239,6 +242,7 @@ def _rule_reason(rule, r) -> dict:
         "modelingv2only",
         "agentflowonly",
         "openengineonly",
+        "docsonly",
     }
 )
 

jenkins/scripts/cbts/rules/README.md

@@ -11,12 +11,33 @@ for the overall CBTS architecture.
 | `waives_rule.py` | `WaivesRule` | `waiveonly` | `tests/integration/test_lists/waives.txt` |
 | `tests_def_rule.py` | `TestsDefRule` | `testdefonly` | `tests/**/*` (any file under tests/) |
 | `test_list_rule.py` | `TestListRule` | `testlistonly` | `tests/integration/test_lists/test-db/*.yml` |
-| `visual_gen_rule.py` | `VisualGenRule` | `visualgenonly` | `examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`, `tensorrt_llm/media/**`, `tensorrt_llm/visual_gen/**` (each excl. `.md`) |
-| `spec_dec_rule.py` | `SpecDecRule` | `specdeconly` | `tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py` (each excl. `.md`) |
-| `modeling_v2_rule.py` | `ModelingV2Rule` | `modelingv2only` | `tensorrt_llm/_torch/_experimental/modeling_v2/**` (excl. `.md`) |
-| `agent_flow_rule.py` | `AgentFlowRule` | `agentflowonly` | `agent-flow/**` (excl. `.md`) → the single `CPU-AgentFlow-UnitTest` stage; not test-db-driven |
-| `openengine_rule.py` | `OpenEngineRule` | `openengineonly` | `tensorrt_llm/grpc/openengine/**` (excl. `.md`) → the `l0_cpu` block containing `unittest/grpc/openengine/` |
-| `out_of_scope_rule.py` | `OutOfScopeRule` | `noop` | `tests/integration/test_lists/{qa,dev}/**`, `tests/integration/defs/.test_durations*`, `tests/microbenchmarks/**`, `**/*.md` (image suffixes intentionally not claimed — fall back to baseline since fixtures and doc diagrams are indistinguishable by location) |
+| `visual_gen_rule.py` | `VisualGenRule` | `visualgenonly` | `examples/visual_gen/**`, `scripts/visualgen_eval/**`, `tensorrt_llm/_torch/visual_gen/**`, `tensorrt_llm/media/**`, `tensorrt_llm/visual_gen/**` (each excl. docs) |
+| `spec_dec_rule.py` | `SpecDecRule` | `specdeconly` | `tensorrt_llm/_torch/speculative/**`, `tensorrt_llm/models/{eagle,medusa,redrafter}/**`, `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/**`, `examples/llm-api/llm_speculative_decoding.py` (each excl. docs) |
+| `modeling_v2_rule.py` | `ModelingV2Rule` | `modelingv2only` | `tensorrt_llm/_torch/_experimental/modeling_v2/**` (excl. docs) |
+| `agent_flow_rule.py` | `AgentFlowRule` | `agentflowonly` | `agent-flow/**` (excl. docs) → the single `CPU-AgentFlow-UnitTest` stage; not test-db-driven |
+| `openengine_rule.py` | `OpenEngineRule` | `openengineonly` | `tensorrt_llm/grpc/openengine/**` (excl. docs) → the `l0_cpu` block containing `unittest/grpc/openengine/` |
+| `docs_rule.py` | `DocsRule` | `docsonly` | `docs/**` → `CPU-Build_Docs` plus complete `l0_cpu`; other `**/*.md` / `**/*.rst` → `CPU-Build_Docs` only |
+| `out_of_scope_rule.py` | `OutOfScopeRule` | `noop` | `.github/CODEOWNERS`, `tests/integration/test_lists/{qa,dev}/**`, `tests/integration/defs/.test_durations*`, `tests/microbenchmarks/**` (image suffixes intentionally not claimed — fall back to baseline since fixtures and doc diagrams are indistinguishable by location) |
+
+## DocsRule
+
+Claims every file under `docs/` plus Markdown and reStructuredText files
+anywhere in the repository. Every claim contributes the literal
+`CPU-Build_Docs` stage, which runs Doxygen and Sphinx `make html`. Changes under
+`docs/` additionally keep every block and entry in `l0_cpu.yml`, because CPU
+tests directly read documentation sources such as `model-express.md` and import
+the telemetry extension under `docs/source/_ext/`. If the CPU test-db blocks or
+stages cannot be resolved for a `docs/` change, the rule forces fallback instead
+of silently running docs alone. Markdown and reStructuredText outside `docs/`
+run only the docs build, matching the legacy Docs path without adding unrelated
+CPU tests.
+
+On a docs-only PR, `L0_MergeRequest.groovy` skips the SBSA build track, so the
+resolved `CPU-Generic-arm-*` stage is recorded in `affected_stages` but is not
+launched; the x86 CPU stage supplies the CPU validation. Mixed PRs continue to
+follow the normal architecture gates. Documentation files inside another rule's
+source prefix remain excluded from that source rule, and mixed documentation
+and targeted-test changes combine by unioning their stages.
 
 ## WaivesRule
 
@@ -210,7 +231,7 @@ Path-only rule. Claims source files under `tensorrt_llm/_torch/speculative/`,
 `tensorrt_llm/models/{eagle,medusa,redrafter}/`,
 `examples/{eagle,medusa,redrafter,draft_target_model,ngram}/`, and the
 single file `examples/llm-api/llm_speculative_decoding.py` (excluding
-`.md`, which `OutOfScopeRule` claims as noop). Other suffixes —
+documentation paths, which `DocsRule` routes to `CPU-Build_Docs`). Other suffixes —
 including images — are NOT excluded: a binary asset under a spec-dec
 path could be a test fixture, so the rule keeps claiming them and
 forces spec-dec stages to re-run.
@@ -332,7 +353,6 @@ in any subtree neither pre-merge nor post-merge L0 consumes:
   consumer.
 - `tests/integration/defs/.test_durations` — pytest-split timing cache.
 - `tests/microbenchmarks/` — benchmarking scripts, no L0 stage.
-- Any `*.md` file (docs anywhere in the repo cannot affect L0 tests).
 
 Image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`) are
 intentionally NOT claimed: image files anywhere in the repo can be test
@@ -342,9 +362,9 @@ distinguish a fixture from a doc diagram. Image edits therefore fall
 back to baseline unless a more specific rule (AD / VG / spec-dec)
 claims them inside its source subtree.
 
-Excludes `*.txt` (`requirements.txt` / `constraints.txt` are
-runtime-relevant). `OUT_OF_SCOPE_PREFIXES` and `OUT_OF_SCOPE_SUFFIXES`
-in `out_of_scope_rule.py` list the patterns.
+Excludes `*.txt` (`requirements.txt` / `constraints.txt` are runtime-relevant).
+`OUT_OF_SCOPE_EXACT_PATHS` and `OUT_OF_SCOPE_PREFIXES` in
+`out_of_scope_rule.py` list the patterns.
 
 ## Helpers (`_helpers.py`)
 

jenkins/scripts/cbts/rules/agent_flow_rule.py

@@ -34,6 +34,7 @@
 from blocks import Stage, YAMLIndex
 
 from .base import PRInputs, Rule, RuleResult
+from .docs_rule import is_docs_path
 
 # Stage key as declared in jenkins/L0_Test.groovy. Keep in sync.
 AGENT_FLOW_STAGE = "CPU-AgentFlow-UnitTest"
@@ -47,13 +48,13 @@ def _is_agent_flow_claim(path: str) -> bool:
 
     Claims everything under ``agent-flow/`` — source, tests, and build
     metadata (``pyproject.toml``, ``.pre-commit-config.yaml``) all affect
-    what the pytest stage installs and runs — except ``*.md`` docs, which
-    ``OutOfScopeRule`` claims as noop so a docs-only edit doesn't force the
-    stage.
+    what the pytest stage installs and runs — except documentation files,
+    which ``DocsRule`` routes to the dedicated docs build so a docs-only
+    edit doesn't force the agent-flow test stage.
     """
     if not path.startswith(_AGENT_FLOW_PREFIX):
         return False
-    if path.endswith(".md"):
+    if is_docs_path(path):
         return False
     return True