diff --git a/docs/mkdocs/hooks/generate_examples.py b/docs/mkdocs/hooks/generate_examples.py index 6627fd010..c33cd8f7f 100644 --- a/docs/mkdocs/hooks/generate_examples.py +++ b/docs/mkdocs/hooks/generate_examples.py @@ -41,17 +41,6 @@ GENERAL_EXAMPLE_SLUGS = frozenset( } ) -# Generated example pages keep their source-derived URLs even when their -# navigation category changes. Quantization helpers are feature documentation, -# not user-serving examples, so keep them under the existing Features / -# Quantization section instead of creating a second top-level Quantization -# category under Examples. -EXAMPLE_NAV_TARGETS = { - "quantization": "quantization", -} -GENERATED_QUANTIZATION_EXAMPLES_TITLE = "Generated Examples" - - def load_model_display_names() -> dict[str, str]: try: with open(MODEL_DISPLAY_NAMES_FILE, encoding="utf-8") as f: @@ -382,12 +371,9 @@ def update_nav_file(examples: list[Example]): items.append({example.nav_title: rel_path.as_posix()}) return items - # Build the new Examples section - start with preserved items. Categories - # not explicitly routed elsewhere retain the historical Examples behavior. + # Build the new Examples section - start with preserved items. examples_section = preserved_items.copy() for category in sorted(examples_by_category.keys()): - if EXAMPLE_NAV_TARGETS.get(category, "examples") != "examples": - continue items = category_items(category) if items: category_title = fix_case(category.replace("_", " ").title()) @@ -396,36 +382,6 @@ def update_nav_file(examples: list[Example]): # Update the nav structure nav_list[user_guide_idx]["User Guide"][examples_idx]["Examples"] = examples_section - features_content = next( - (item["Features"] for item in user_guide_content if isinstance(item, dict) and "Features" in item), - None, - ) - quantization_content = None - if isinstance(features_content, list): - quantization_content = next( - (item["Quantization"] for item in features_content if isinstance(item, dict) and "Quantization" in item), - None, - ) - - if isinstance(quantization_content, list): - # Remove only the group owned by this hook so repeated builds are - # idempotent and hand-authored Quantization navigation is retained. - quantization_content[:] = [ - item - for item in quantization_content - if not (isinstance(item, dict) and GENERATED_QUANTIZATION_EXAMPLES_TITLE in item) - ] - - quantization_examples = examples_by_category.get("quantization") - if quantization_examples: - if not isinstance(quantization_content, list): - logger.warning( - "Could not find 'User Guide' -> 'Features' -> 'Quantization' section; " - "omitting generated quantization examples from navigation" - ) - else: - quantization_content.append({GENERATED_QUANTIZATION_EXAMPLES_TITLE: category_items("quantization")}) - # Write back to file nav_data["nav"] = nav_list with open(NAV_FILE, "w", encoding="utf-8") as f: diff --git a/tests/docs/test_generate_examples.py b/tests/docs/test_generate_examples.py index 1e2781600..9883e387d 100644 --- a/tests/docs/test_generate_examples.py +++ b/tests/docs/test_generate_examples.py @@ -6,7 +6,6 @@ from pathlib import Path from types import SimpleNamespace import pytest -import yaml pytestmark = [pytest.mark.core_model, pytest.mark.cpu] @@ -53,113 +52,3 @@ def test_only_general_serving_examples_get_generated_pages(): assert generate_examples.is_general_example(general_example) assert not generate_examples.is_general_example(model_example) - - -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