[Docs] Preserve generated quantization URLs and link recipes in supported models (#5969)

Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>

tests/docs/test_generate_examples.py

@@ -3,8 +3,10 @@
 
 import importlib.util
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
+import yaml
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
@@ -43,3 +45,113 @@ def test_model_display_names_require_string_mapping(tmp_path, monkeypatch):
 
     with pytest.raises(ValueError, match="MODEL_DISPLAY_NAMES_FILE"):
         generate_examples.load_model_display_names()
+
+
+def test_quantization_examples_keep_source_urls_under_feature_navigation(tmp_path, monkeypatch):
+    nav_file = tmp_path / "docs" / ".nav.yml"
+    nav_file.parent.mkdir(parents=True)
+    nav_file.write_text(
+        yaml.safe_dump(
+            {
+                "nav": [
+                    {
+                        "User Guide": [
+                            {
+                                "Examples": [
+                                    "examples/README.md",
+                                    {"Offline Inference": [{"Old": "user_guide/examples/offline_inference/old.md"}]},
+                                ]
+                            },
+                            {"Features": [{"Quantization": [{"Overview": "user_guide/quantization/overview.md"}]}]},
+                        ]
+                    }
+                ]
+            },
+            sort_keys=False,
+        ),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setattr(generate_examples, "ROOT_DIR", tmp_path)
+    monkeypatch.setattr(generate_examples, "NAV_FILE", nav_file)
+    monkeypatch.setattr(generate_examples, "EXAMPLE_DOC_DIR", tmp_path / "docs/user_guide/examples")
+
+    quantization_example = SimpleNamespace(
+        category="quantization",
+        path=tmp_path / "examples/quantization/check_modelopt_fp8_export.py",
+        nav_title="Check Modelopt FP8 Export",
+    )
+    offline_example = SimpleNamespace(
+        category="offline_inference",
+        path=tmp_path / "examples/offline_inference/demo.py",
+        nav_title="Demo",
+    )
+
+    generate_examples.update_nav_file([quantization_example, offline_example])
+    generate_examples.update_nav_file([quantization_example, offline_example])
+
+    nav_data = yaml.safe_load(nav_file.read_text(encoding="utf-8"))
+    user_guide = nav_data["nav"][0]["User Guide"]
+    examples = next(item["Examples"] for item in user_guide if "Examples" in item)
+    features = next(item["Features"] for item in user_guide if "Features" in item)
+    quantization = next(item["Quantization"] for item in features if "Quantization" in item)
+
+    assert not any(isinstance(item, dict) and "Quantization" in item for item in examples)
+    generated_examples = [
+        item[generate_examples.GENERATED_QUANTIZATION_EXAMPLES_TITLE]
+        for item in quantization
+        if generate_examples.GENERATED_QUANTIZATION_EXAMPLES_TITLE in item
+    ]
+    assert len(generated_examples) == 1
+    assert generated_examples[0] == [
+        {"Check Modelopt FP8 Export": "user_guide/examples/quantization/check_modelopt_fp8_export.md"}
+    ]
+
+    # A later build without quantization examples must not leave a stale
+    # generated group in the hand-authored Quantization section.
+    generate_examples.update_nav_file([offline_example])
+    nav_data = yaml.safe_load(nav_file.read_text(encoding="utf-8"))
+    user_guide = nav_data["nav"][0]["User Guide"]
+    features = next(item["Features"] for item in user_guide if "Features" in item)
+    quantization = next(item["Quantization"] for item in features if "Quantization" in item)
+    assert not any(
+        isinstance(item, dict) and generate_examples.GENERATED_QUANTIZATION_EXAMPLES_TITLE in item
+        for item in quantization
+    )
+
+
+def test_quantization_examples_are_not_added_to_examples_without_feature_target(tmp_path, monkeypatch, caplog):
+    nav_file = tmp_path / "docs" / ".nav.yml"
+    nav_file.parent.mkdir(parents=True)
+    nav_file.write_text(
+        yaml.safe_dump(
+            {
+                "nav": [
+                    {
+                        "User Guide": [
+                            {"Examples": ["examples/README.md"]},
+                        ]
+                    }
+                ]
+            },
+            sort_keys=False,
+        ),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setattr(generate_examples, "ROOT_DIR", tmp_path)
+    monkeypatch.setattr(generate_examples, "NAV_FILE", nav_file)
+    monkeypatch.setattr(generate_examples, "EXAMPLE_DOC_DIR", tmp_path / "docs/user_guide/examples")
+
+    quantization_example = SimpleNamespace(
+        category="quantization",
+        path=tmp_path / "examples/quantization/check_modelopt_fp8_export.py",
+        nav_title="Check Modelopt FP8 Export",
+    )
+
+    generate_examples.update_nav_file([quantization_example])
+
+    nav_data = yaml.safe_load(nav_file.read_text(encoding="utf-8"))
+    examples = nav_data["nav"][0]["User Guide"][0]["Examples"]
+    assert not any(isinstance(item, dict) and "Quantization" in item for item in examples)
+    assert "omitting generated quantization examples from navigation" in caplog.text