diff --git a/build_support/catalog/test_update.py b/build_support/catalog/test_update.py index 1ee941b6c..b3abfa56b 100644 --- a/build_support/catalog/test_update.py +++ b/build_support/catalog/test_update.py @@ -821,3 +821,27 @@ def test_empty_catalog_produces_valid_am(self, tmp_path): update.update_makefile(catalog_dir=tmp_path, am_path=am) content = am.read_text() assert content.startswith("CATALOG_FILES =") + + +@pytest.mark.catalog_update +class TestWarnMissingDescriptions: + """Tests for ``_warn_missing_descriptions(df)``. + + The function prints to stderr for each game in a supported format that has + an empty description. Tests use ``capsys`` to capture stderr output. + """ + + def test_game_without_description_warns(self, capsys): + """A game with an empty description produces a WARNING on stderr.""" + df = _make_df(_efg_row("journals/nobody2025/fig1", description="")) + update._warn_missing_descriptions(df) + err = capsys.readouterr().err + assert "WARNING" in err + assert "journals/nobody2025/fig1" in err + + def test_game_with_description_does_not_warn(self, capsys): + """A game with a non-empty description produces no output.""" + df = _make_df(_efg_row("journals/nobody2025/fig1")) + update._warn_missing_descriptions(df) + err = capsys.readouterr().err + assert err == "" diff --git a/build_support/catalog/update.py b/build_support/catalog/update.py index f61acc014..ccfb77634 100644 --- a/build_support/catalog/update.py +++ b/build_support/catalog/update.py @@ -1,5 +1,6 @@ import argparse import shutil +import sys from pathlib import Path import pandas as pd @@ -93,6 +94,23 @@ def _node_label(prefix: str, labels: dict[str, str]) -> str: return Path(prefix).name.replace("_", " ").title() +def _warn_missing_descriptions(df: pd.DataFrame) -> None: + """Print a warning to stderr for each game that lacks a description. + + Games without descriptions are silently excluded from the catalog page by + ``_build_slug_tree``. This function makes that visible so contributors + know to add a description before the game will appear. + """ + for _, row in df.iterrows(): + if str(row.get("Description", "")).strip(): + continue + print( + f"WARNING: '{row['Game']}' has no description and will not appear in the catalog.\n" + f"Add a description to the game file to include it.", + file=sys.stderr, + ) + + def _build_slug_tree(df: pd.DataFrame) -> dict: """Build a nested dict tree from the slugs in *df*. @@ -392,6 +410,7 @@ def update_makefile( # Create RST list-table used by doc/catalog.rst df = gbt.catalog.games(include_descriptions=True) + _warn_missing_descriptions(df) generate_rst_table(df, CATALOG_RST_TABLE, regenerate_images=args.regenerate_images) print(f"Generated {CATALOG_RST_TABLE} for use in local docs build. DO NOT COMMIT.") if args.build: