Skip to content

docs(classify): fix stale example outputs and add missing examples#3516

Merged
brendancol merged 3 commits into
xarray-contrib:mainfrom
brendancol:deep-sweep-documentation-classify-2026-06-25
Jun 26, 2026
Merged

docs(classify): fix stale example outputs and add missing examples#3516
brendancol merged 3 commits into
xarray-contrib:mainfrom
brendancol:deep-sweep-documentation-classify-2026-06-25

Conversation

@brendancol

Copy link
Copy Markdown
Contributor

Fixes the documentation issues found by the documentation sweep on the classify module (#3506).

Stale / wrong example output

  • reclassify: the numpy, dask, and cupy example blocks all printed an array that does not match the function's result for the example input. Corrected all three to the actual output.
  • equal_interval: the example printed a stale array. Corrected to the actual output.
  • binary: the example used np.nan in the array repr where numpy prints nan. Fixed.

test_classify.py fixtures confirm the functions return the corrected values, so the code was right and only the docstrings were stale.

Missing Examples

Added an Examples section to std_mean, head_tail_breaks, percentiles, maximum_breaks, and box_plot. Each output was generated by running the function and pasted verbatim.

Scope

Docs only. No behavior change. test_classify.py passes (102) and flake8 is clean.

The natural_breaks num_sample/None type omission (already tracked in #3501) is intentionally left out of this PR.

The reclassify and equal_interval docstring examples printed arrays that
do not match what the functions return for the given input; binary used
np.nan in the array repr where numpy prints plain nan. Correct all three
to the actual output (test_classify.py fixtures confirm the code is
right, so only the docstrings were stale).

Add Examples sections to std_mean, head_tail_breaks, percentiles,
maximum_breaks, and box_plot, which had Parameters/Returns/References
but no example.

Docs only; no behavior change.

Refs xarray-contrib#3506
Address review feedback on PR xarray-contrib#3516: the reclassify docstring still
showed pre-refactor lazy reprs next to the corrected result arrays.

- agg_da repr: dtype float32 -> float64 (the example input is float64)
- lazy result repr: task name _run_numpy_bin -> xrspatial.reclassify
  (renamed via _dask_task_name_kwargs)
- cupy type: cupy.core.core.ndarray -> cupy.ndarray

Verified each repr against output on a CUDA host. Docs only.

Refs xarray-contrib#3506
@brendancol

Copy link
Copy Markdown
Contributor Author

Review: classify docstring examples

Re-ran every docstring example on a CUDA host and diffed the printed output against actual output.

Blockers: none.

Suggestion (fixed in ef98faa): the reclassify docstring had its three result arrays corrected by the PR, but the surrounding lazy reprs in the same docstring were still stale:

  • the agg_da repr showed dtype=float32, but the float64 input gives dtype=float64
  • the lazy result repr showed dask.array<_run_numpy_bin, ...>; the current task name is dask.array<xrspatial.reclassify, ...> after the _dask_task_name_kwargs rename
  • the cupy block printed <class 'cupy.core.core.ndarray'>; current cupy returns <class 'cupy.ndarray'>

All three corrected against live output.

Nit (left as-is): the example headers omit the Size: NNB suffix modern xarray prints. Kept consistent with the other examples in this module (quantile, natural_breaks); these are .. sourcecode:: blocks, not doctests.

What looks good: the two genuinely wrong outputs (reclassify, equal_interval) now match actual output; the five new Examples print exactly what the functions produce; docs-only with no behavior change; 102 tests pass; flake8 clean.

…ion-classify-2026-06-25

# Conflicts:
#	.claude/sweep-documentation-state.csv
@brendancol brendancol merged commit 3861372 into xarray-contrib:main Jun 26, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant