Merge pull request #50 from tidy-finance/docs/update-great-docs-config

Update great-docs.yml config

Author: christophscheuch

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## Project layout
+
+- `tidyfinance/` — the package.
+  - `__init__.py` — builds the public API automatically by scanning the
+    public submodules and re-exporting their functions/classes (see
+    `__all__`). Data-bearing functions are wrapped at this boundary by
+    `backend._use_backend` so they honor the active polars/pandas backend.
+    Keep this file's namespace clean: discovery loop variables, imports
+    (`importlib`, `pkgutil`, `types`), and internal toggles are deleted or
+    underscore-prefixed at the end so they don't leak into `dir(tidyfinance)`
+    or the docs.
+  - `core.py` — analytics functions (portfolio sorts, breakpoints, beta /
+    Fama-MacBeth estimation, lagging, summary statistics).
+  - `data_download.py` — `download_data` and the WRDS / Fama-French / FRED /
+    OSAP / Hugging Face download helpers.
+  - `backend.py` — `set_backend` / `get_backend` and the internal
+    `_use_backend` decorator.
+  - `utilities.py`, `supported_datasets.py` — helpers and dataset metadata.
+  - `_internal.py`, `_pseudo.py` — private modules.
+
+## Conventions
+
+### Docstrings
+
+- NumPy-style docstrings, parsed by Great Docs (griffe, `parser: numpy`).
+- **Examples must use fenced ` ```python ` code blocks, NOT doctest `>>>` /
+  `...` prompts.** The Great Docs copy button copies code verbatim, and
+  prompts make examples impossible to paste and run. Write:
+
+  ````
+  Examples
+  --------
+  ```python
+  import numpy as np
+  from tidyfinance import winsorize
+  data = np.random.default_rng(123).standard_normal(100)
+  winsorized = winsorize(data, 0.05)
+  ```
+  ````
+
+  Do not reintroduce `>>>` examples. If you ever need verifiable doctests
+  with expected output, raise it as a deliberate change — the current
+  examples are input-only and carry no doctest assertions.
+
+### Public API
+
+- A function is part of the public API by living in a public (non-`_`)
+  submodule as a function/class defined within the package — it is then
+  auto-discovered and re-exported from `tidyfinance`.
+- To keep something out of the public API and the Reference page, prefix it
+  with `_` (module or name).
+- Do not name a module `core`, `utils`, `helpers`, `constants`, `config`, or
+  `settings` and expect it to appear in the docs: Great Docs auto-excludes
+  those names. `core` is kept only because `great-docs.yml` lists it under
+  `auto_include`.
+
+### Style
+
+- Ruff, `line-length = 80` (`[tool.ruff]` in `pyproject.toml`). Keep code
+  and docstrings within 80 columns.
+
+## Common commands
+
+This project uses `uv`.
+
+```bash
+uv run pytest                 # run the test suite (tests/test_*.py)
+uv run pytest tests/test_core.py
+uv run ruff check .           # lint
+uv run ruff format .          # format
+```
+
+Every public function should have a matching `tests/test_<name>.py`.
+
+## Documentation (Great Docs)
+
+- Config: `great-docs.yml`. Generated output lives in `great-docs/`
+  (git-ignored build artifacts).
+
+```bash
+uv run great-docs build       # build the site
+uv run great-docs preview --port 3000   # local preview (auto-rebuilds)
+uv run great-docs scan        # preview what will be discovered as public API
+```
+

great-docs.yml

@@ -5,7 +5,7 @@
 # ----------------------
 # Set this if your importable module name differs from the project name.
 # Example: project 'py-yaml12' with module name 'yaml12'
-# module: yaml12
+module: tidyfinance
 
 # Docstring Parser
 # ----------------
@@ -25,6 +25,12 @@ dynamic: true
 #   - InternalClass
 #   - helper_function
 
+# Force-include modules that Great Docs auto-excludes as generic
+# "re-export" names. Our analytics functions live in 'core', which is
+# on that blocklist, so it must be re-included for them to be documented.
+auto_include:
+  - core
+
 # Logo & Favicon
 # ---------------
 # Point to a single logo file (replaces the text title in the navbar):
@@ -48,14 +54,21 @@ authors:
     email: christoph.frey@gmail.com
     # github: 
     # orcid: 
-    # homepage: 
+    homepage: https://sites.google.com/site/christophfrey/
   - name: Christoph Scheuch
     role: Author
     # affiliation: 
     email: christoph@tidy-intelligence.com
     # github: 
     # orcid: 
-    # homepage: 
+    homepage: https://christophscheuch.github.io/
+  - name: Stefan Voigt
+    role: Author
+    # affiliation: 
+    email: stefan.voigt@econ.ku.dk
+    # github: 
+    # orcid: 
+    homepage: https://www.voigtstefan.me/
 
 # Funding / Copyright Holder
 # --------------------------

tests/test_add_lagged_columns.py

@@ -18,9 +18,7 @@ def test_exact_lag_with_by_returns_correct_lagged_values():
     data = pd.DataFrame(
         {
             "permno": [1] * 4 + [2] * 4,
-            "date": list(
-                pd.date_range("2023-01-01", periods=4, freq="MS")
-            ) * 2,
+            "date": list(pd.date_range("2023-01-01", periods=4, freq="MS")) * 2,
             "size": [float(i) for i in range(1, 9)],
         }
     )
@@ -41,9 +39,7 @@ def test_exact_lag_without_by_returns_correct_values():
             "size": [1.0, 2.0, 3.0],
         }
     )
-    result = add_lagged_columns(
-        data, cols="size", lag=pd.DateOffset(months=1)
-    )
+    result = add_lagged_columns(data, cols="size", lag=pd.DateOffset(months=1))
     assert pd.isna(result["size_lag"].iloc[0])
     assert result["size_lag"].iloc[1] == 1
     assert result["size_lag"].iloc[2] == 2
@@ -53,9 +49,7 @@ def test_window_lag_handles_all_src_date_conditions():
     """Test window lag: NA, in-window, and below-lower-bound cases."""
     data = pd.DataFrame(
         {
-            "date": pd.to_datetime(
-                ["2023-01-01", "2023-02-01", "2023-06-01"]
-            ),
+            "date": pd.to_datetime(["2023-01-01", "2023-02-01", "2023-06-01"]),
             "size": [1.0, 2.0, 3.0],
         }
     )
@@ -104,9 +98,7 @@ def test_ff_adjustment_without_by_uses_year_grouping_only():
     """Test ff_adjustment without by uses year grouping only."""
     data = pd.DataFrame(
         {
-            "date": pd.to_datetime(
-                ["2022-06-01", "2022-12-01", "2023-06-01"]
-            ),
+            "date": pd.to_datetime(["2022-06-01", "2022-12-01", "2023-06-01"]),
             "size": [10.0, 20.0, 30.0],
         }
     )
@@ -152,18 +144,14 @@ def test_error_when_date_column_is_absent_from_data():
 
 def test_error_when_lag_is_negative():
     """Test error when lag is negative."""
-    data = pd.DataFrame(
-        {"date": [pd.Timestamp("2023-01-01")], "size": [1.0]}
-    )
+    data = pd.DataFrame({"date": [pd.Timestamp("2023-01-01")], "size": [1.0]})
     with pytest.raises(ValueError, match="non-negative"):
         add_lagged_columns(data, cols="size", lag=-1)
 
 
 def test_error_when_max_lag_is_less_than_lag():
     """Test error when max_lag is less than lag."""
-    data = pd.DataFrame(
-        {"date": [pd.Timestamp("2023-01-01")], "size": [1.0]}
-    )
+    data = pd.DataFrame({"date": [pd.Timestamp("2023-01-01")], "size": [1.0]})
     with pytest.raises(ValueError, match="max_lag"):
         add_lagged_columns(
             data,
@@ -175,9 +163,7 @@ def test_error_when_max_lag_is_less_than_lag():
 
 def test_error_when_requested_column_is_absent_from_data():
     """Test error when a requested column is absent from data."""
-    data = pd.DataFrame(
-        {"date": [pd.Timestamp("2023-01-01")], "size": [1.0]}
-    )
+    data = pd.DataFrame({"date": [pd.Timestamp("2023-01-01")], "size": [1.0]})
     with pytest.raises(ValueError, match="missing"):
         add_lagged_columns(
             data, cols="no_such_col", lag=pd.DateOffset(months=1)
@@ -186,9 +172,7 @@ def test_error_when_requested_column_is_absent_from_data():
 
 def test_error_when_by_column_is_absent_from_data():
     """Test error when a by column is absent from data."""
-    data = pd.DataFrame(
-        {"date": [pd.Timestamp("2023-01-01")], "size": [1.0]}
-    )
+    data = pd.DataFrame({"date": [pd.Timestamp("2023-01-01")], "size": [1.0]})
     with pytest.raises(ValueError, match="missing"):
         add_lagged_columns(
             data,
@@ -207,9 +191,7 @@ def test_error_when_join_key_is_not_unique():
         }
     )
     with pytest.raises(ValueError, match="unique"):
-        add_lagged_columns(
-            data, cols="size", lag=pd.DateOffset(months=1)
-        )
+        add_lagged_columns(data, cols="size", lag=pd.DateOffset(months=1))
 
 
 def test_error_when_upper_helper_column_already_exists():
@@ -233,6 +215,7 @@ def test_error_when_upper_helper_column_already_exists():
 def test_data_options_specifies_date_column_name():
     """Test data_options dict specifies the date column name."""
     from tidyfinance.core import data_options
+
     data = pd.DataFrame(
         {
             "my_date": pd.date_range("2023-01-01", periods=3, freq="MS"),
@@ -249,6 +232,7 @@ def test_data_options_specifies_date_column_name():
     assert pd.isna(result["size_lag"].iloc[0])
     assert result["size_lag"].iloc[1] == 1
 
+
 if __name__ == "__main__":
     # Run all tests
     pytest.main([__file__])

tests/test_assign_portfolio.py

@@ -14,7 +14,6 @@
 
 from tidyfinance.core import assign_portfolio  # noqa: E402
 
-
 # %% mock breakpoint functions
 
 
@@ -31,9 +30,7 @@ def mock_breakpoint_percentiles(
     data, sorting_variable, bp_options=None, data_options=None
 ):
     """Percentile-based mock breakpoint function."""
-    percentiles = (bp_options or {}).get(
-        "percentiles", [0.2, 0.4, 0.6, 0.8]
-    )
+    percentiles = (bp_options or {}).get("percentiles", [0.2, 0.4, 0.6, 0.8])
     probs = [0] + list(percentiles) + [1]
     return np.quantile(data[sorting_variable].dropna().values, probs)
 
@@ -156,9 +153,7 @@ def test_constant_sorting_variable_returns_vector_of_correct_length():
 
 def test_two_distinct_values_with_2_portfolios_produces_two_groups():
     """Test two distinct values with 2 portfolios produces two groups."""
-    data = pd.DataFrame(
-        {"id": range(100), "value": [1] * 50 + [2] * 50}
-    )
+    data = pd.DataFrame({"id": range(100), "value": [1] * 50 + [2] * 50})
     result = assign_portfolio(
         data,
         "value",
@@ -189,9 +184,7 @@ def test_single_row_data_frame_with_constant_variable_triggers_warning():
 
 def test_warning_when_clusters_reduce_number_of_portfolios():
     """Test warning is issued when clusters reduce the number of portfolios."""
-    data = pd.DataFrame(
-        {"id": range(100), "value": [1] * 50 + [100] * 50}
-    )
+    data = pd.DataFrame({"id": range(100), "value": [1] * 50 + [100] * 50})
 
     def mock_bp_5(data, sv, bp_options=None, data_options=None):
         return np.array([1, 20, 40, 60, 80, 100])
@@ -335,9 +328,7 @@ def test_function_works_with_large_datasets():
     """Test function works with large datasets."""
     rng = np.random.default_rng(1)
     n = 100_000
-    data = pd.DataFrame(
-        {"id": np.arange(n), "value": rng.standard_normal(n)}
-    )
+    data = pd.DataFrame({"id": np.arange(n), "value": rng.standard_normal(n)})
     result = assign_portfolio(
         data,
         "value",
@@ -416,9 +407,7 @@ def test_percentile_based_breakpoints_produce_correct_number_of_groups():
 def test_two_portfolios_split_data_roughly_in_half():
     """Test two portfolios split data roughly in half."""
     rng = np.random.default_rng(10)
-    data = pd.DataFrame(
-        {"id": range(1000), "value": rng.standard_normal(1000)}
-    )
+    data = pd.DataFrame({"id": range(1000), "value": rng.standard_normal(1000)})
     result = assign_portfolio(
         data,
         "value",
@@ -444,9 +433,7 @@ def spy_bp(data, sorting_variable, bp_options=None, data_options=None):
         received["data_options"] = data_options
         return np.array([0.0, 0.5, 1.0])
 
-    data = pd.DataFrame(
-        {"id": range(10), "value": np.linspace(0, 1, 10)}
-    )
+    data = pd.DataFrame({"id": range(10), "value": np.linspace(0, 1, 10)})
     my_bp_opts = {"n_portfolios": 2}
     my_data_opts = {"date": "date_col"}
     assign_portfolio(