fix(docs): unwrap load_prop99 docstring bullet (Sphinx -W) + extend doc-snippet mock loaders with prop99/walmart

The doc-snippets harness replaces sys.modules['diff_diff.datasets'] with a
mock module; the new loaders' snippets need mock counterparts there. The
wrapped Returns bullet in load_prop99 broke the -W docs build (unexpected
indentation).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FZK3FD9jxWGxBrPDw5APSg

Author: igerber

diff_diff/datasets.py

@@ -828,8 +828,7 @@ def load_prop99(force_download: bool = False) -> pd.DataFrame:
         Panel dataset with columns:
         - state : str - State name
         - year : int - Year (1970-2000)
-        - first_year : int - Year treatment began (1989 for California,
-          0 = never treated)
+        - first_year : int - Treatment start year (1989 for California, 0 = never)
         - lcigsale : float - Log per capita cigarette sales (packs)
         - treated : int - 1 if treatment in effect, 0 otherwise
         - cohort : int - Alias for first_year

tests/test_doc_snippets.py

@@ -287,11 +287,51 @@ def _mock_load_mpdta(**kwargs):
             }
         )
 
+    def _mock_load_prop99(**kwargs):
+        states = ["California"] + [f"State{i:02d}" for i in range(2, 11)]
+        years = list(range(1980, 1996))
+        rows = [(s, y) for s in states for y in years]
+        fy = [1989 if r[0] == "California" else 0 for r in rows]
+        return pd.DataFrame(
+            {
+                "state": [r[0] for r in rows],
+                "year": [r[1] for r in rows],
+                "first_year": fy,
+                "lcigsale": rng.normal(4.6, 0.1, len(rows)),
+                "treated": [1 if f and r[1] >= f else 0 for f, r in zip(fy, rows)],
+                "cohort": fy,
+            }
+        )
+
+    def _mock_load_walmart(**kwargs):
+        counties = list(range(1, 21))
+        years = list(range(1985, 1996))
+        rows = [(c, y) for c in counties for y in years]
+        n = len(rows)
+        cohort_of = {c: (0 if c <= 8 else [1988, 1990, 1992][c % 3]) for c in counties}
+        fy = [cohort_of[r[0]] for r in rows]
+        return pd.DataFrame(
+            {
+                "cid": [r[0] for r in rows],
+                "year": [r[1] for r in rows],
+                "first_year": fy,
+                "log_retail_emp": rng.normal(7.5, 0.5, n),
+                "log_wholesale_emp": rng.normal(6.5, 0.5, n),
+                "x1": rng.uniform(0.05, 0.3, n),
+                "x2": rng.uniform(0.5, 0.85, n),
+                "x3": rng.uniform(0.05, 0.4, n),
+                "treated": [1 if f and r[1] >= f else 0 for f, r in zip(fy, rows)],
+                "cohort": fy,
+            }
+        )
+
     _dataset_dispatch = {
         "card_krueger": _mock_load_card_krueger,
         "castle_doctrine": _mock_load_castle_doctrine,
         "divorce_laws": _mock_load_divorce_laws,
         "mpdta": _mock_load_mpdta,
+        "prop99": _mock_load_prop99,
+        "walmart": _mock_load_walmart,
     }
 
     def _mock_load_dataset(name, **kwargs):
@@ -305,6 +345,8 @@ def _mock_list_datasets():
             "castle_doctrine": "Castle Doctrine laws - staggered adoption",
             "divorce_laws": "Unilateral divorce laws - staggered adoption",
             "mpdta": "Minimum wage panel data - simulated CS example",
+            "prop99": "California Prop 99 smoking panel - single treated unit",
+            "walmart": "Walmart entry county panel - staggered adoption",
         }
 
     # Inject mocks into namespace so `from diff_diff.datasets import ...` works
@@ -315,6 +357,8 @@ def _mock_list_datasets():
     mock_datasets_mod.load_castle_doctrine = _mock_load_castle_doctrine
     mock_datasets_mod.load_divorce_laws = _mock_load_divorce_laws
     mock_datasets_mod.load_mpdta = _mock_load_mpdta
+    mock_datasets_mod.load_prop99 = _mock_load_prop99
+    mock_datasets_mod.load_walmart = _mock_load_walmart
     mock_datasets_mod.load_dataset = _mock_load_dataset
     mock_datasets_mod.list_datasets = _mock_list_datasets
     import sys
@@ -327,6 +371,8 @@ def _mock_list_datasets():
     ns["load_castle_doctrine"] = _mock_load_castle_doctrine
     ns["load_divorce_laws"] = _mock_load_divorce_laws
     ns["load_mpdta"] = _mock_load_mpdta
+    ns["load_prop99"] = _mock_load_prop99
+    ns["load_walmart"] = _mock_load_walmart
     ns["load_dataset"] = _mock_load_dataset
     ns["list_datasets"] = _mock_list_datasets