[MRG] Fixes #343: document cycc functions in tslearn.metrics

[jbbqqf]

Summary

tslearn.metrics re-exports cdist_normalized_cc and y_shifted_sbd_vec (sourced from tslearn/metrics/cycc.py) via __all__, but neither function appears in the Sphinx autosummary for tslearn.metrics, so they are absent from the rendered API reference on readthedocs. Add them so the docs match the public surface.

Fixes #343 — Cross-correlation functions are undocumented

Context

The original report (Feb 2021) noted that after cycc was moved under tslearn.metrics in v0.5, none of its functions showed up in the generated reference at https://tslearn.readthedocs.io/en/stable/gen_modules/tslearn.metrics.html. The exports themselves were kept (tslearn/metrics/__init__.py:61, and both names are listed in __all__), but they were never added to the autosummary block in docs/gen_modules/tslearn.metrics.rst. The normalized_cc helper in the same module is an internal njit function and is not re-exported, so it is intentionally left out of the doc list.

Changes

• docs/gen_modules/tslearn.metrics.rst — add cdist_normalized_cc and y_shifted_sbd_vec to the autosummary list (the existing function docstrings already follow the project's NumPy-style convention).
• tests/test_metrics.py — add test_cycc_functions_documented, a small guard test that fails if either symbol is in tslearn.metrics.__all__ but missing from the rst, so this won't drift back out silently.
• CHANGELOG.md — entry under [Towards v0.9.0] / Changed referencing Cross-correlation functions are undocumented #343.

Reproduce BEFORE/AFTER yourself (copy-paste)

# --- one-time setup ---
git clone https://github.com/tslearn-team/tslearn.git /tmp/repro && cd /tmp/repro
uv venv .venv && . .venv/bin/activate
uv pip install -e . pytest

# --- BEFORE (origin/main) ---
git checkout origin/main
# Borrow the regression test from this PR so the reviewer can see the gap
git fetch https://github.com/jbbqqf/tslearn.git fix/343-document-cycc
git checkout FETCH_HEAD -- tests/test_metrics.py
pytest tests/test_metrics.py::test_cycc_functions_documented -v
# Expected: FAIL — "cdist_normalized_cc is exported by tslearn.metrics but
# missing from docs/gen_modules/tslearn.metrics.rst autosummary"

# --- AFTER (this PR) ---
git checkout FETCH_HEAD
pytest tests/test_metrics.py::test_cycc_functions_documented -v
# Expected: PASS — both names appear in the rst, no other tests affected

What I ran locally

• pytest tests/test_metrics.py::test_cycc_functions_documented -v → 1 passed on the branch, 1 failed when the .rst change is stashed (assertion: cdist_normalized_cc is exported by tslearn.metrics but missing from docs/gen_modules/tslearn.metrics.rst autosummary).
• pytest tests/test_utils.py → 6 passed, 2 skipped (sanity-check that the test infra is unaffected).
• Verified manually that cdist_normalized_cc and y_shifted_sbd_vec are both in tslearn.metrics.__all__ on current main (commit 95bd2d3).

I did not rebuild the Sphinx docs locally — the change is a single addition to an existing autosummary block with the same shape as the surrounding entries, so the html generation path is unchanged.

Edge cases tested

#	Scenario	Input	Expected	Verified by
1	Both names present in __all__ and in rst	current branch	passes	test_cycc_functions_documented
2	Name in __all__ but missing from rst	git stash the rst patch	fails with the missing-name assertion	local run above
3	Internal normalized_cc (not in __all__)	absent from both	not asserted on — intentional, since it is private	manual inspection of tslearn/metrics/__init__.py

Risk / blast radius

Pure docs + test addition. No runtime code touched, no public API changed. The new test only reads files already present in the repo, so it is safe on CI (no network, no heavy compute).

Release note

docs: include `cdist_normalized_cc` and `y_shifted_sbd_vec` in the
`tslearn.metrics` API reference autosummary.

---

PR drafted with assistance from Claude Code. The change was reviewed manually against tslearn-team/tslearn's source on commit 95bd2d3 and the BEFORE/AFTER block above was the one I ran during development; a reviewer can paste it verbatim.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.86%. Comparing base (95bd2d3) to head (bcdc3d2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #676   +/-   ##
=======================================
  Coverage   93.85%   93.86%           
=======================================
  Files          74       74           
  Lines        7081     7092   +11     
=======================================
+ Hits         6646     6657   +11     
  Misses        435      435           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.