docs: array_api.rst limitations section is turning into a changelog; restructure after the array-API PRs land
- Dominant language
- Python
- Stars
- 93
- Forks
- 92
- Avg merge
- 14h 44m
- Merged PRs (30d)
- 30
Description
The "What limitations should I be aware of?" section of `docs/array_api.rst` has grown one bullet per array-API PR (`nanmean`/`nanmedian` fallbacks, `median`, `sigma_func`, `Combiner.sigma_clipping`, and `block_reduce`/`block_average`/`block_replicate` in #1009). Each bullet explains which implementation a function dispatches to and how it was arrived at, so the section now reads as a per-PR changelog rather than user documentation.
Review the section once the block functions (#1009), window filters, and host-copy policy PRs have landed, and restructure it around what a user needs to know:
- one place that states the dispatch rule (numpy input keeps the astropy/scipy code path, every other library gets the array-API implementation) instead of restating it per function;
- a short table of behavioural differences that matter to a user (dtype promotion of integer/bool input, NaN handling on all-NaN slices, boundary classification in sigma clipping, lazy-library `maxiters` advice);
- move the "why" (which library refuses which operation) out of the user docs, into docstrings or developer notes, or drop it.
Raised from review of #1009 (https://github.com/astropy/ccdproc/pull/1009#discussion_r3980158148). Do not fix this in #1009.
Contributor guide
Research direction
Start by reading the limitations section in docs/array_api.rst and review the landed block-functions (#1009), window-filters, and host-copy-policy changes. Restructure the section around one dispatch rule and a concise table covering the listed user-visible behavioural differences; move or remove implementation rationale. Done means the section reads as user documentation rather than a per-PR changelog.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100