docs: document the reexported BandedMatrices API

[ChrisRackauckas]

Follow-up to #82, which restored the explicit reexport of the BandedMatrices names needed for this package's documented use. #82 was merged before this docs pass landed on the branch, so it comes as its own PR.

Requirement: every reexport restoration must also document the reexported surface in the package's own docs, so a reader can see at a glance what using FastAlmostBandedMatrices gives them and which upstream package actually owns each name.

Changes

docs/src/api.md (already wired into docs/make.jl as the "API" page) and the matching README section now give:

• the names grouped by role rather than a flat list — building the bands (BandedMatrix, brand, brandn), populating them (Band, BandRange, band, bandrange), querying them (bandwidth, bandwidths, colrange, rowrange), errors (BandError);
• the owning package named and linked to its docs, https://juliaLinearAlgebra.github.io/BandedMatrices.jl/stable/, stating plainly that FastAlmostBandedMatrices.jl only re-exports these names and neither documents nor defines them;
• an explicit boundary line: anything else from BandedMatrices.jl must be imported from BandedMatrices.jl directly;
• the deliberate exclusions with reasons — the FillArrays.jl names Fill, Ones, Zeros and Eye (BandedMatrices reexports those from a dependency of its own, so passing them along would be reexporting a whole dependency chain, and none of them is needed to build an AlmostBandedMatrix), the BandedMatrices module binding itself, and symrcm;
• a note that Band and BandError have no docstring upstream, which is why they sit in the api_docs_kwargs ignore list in test/qa/qa.jl, and that the docstring is owed by BandedMatrices.jl.

Keeping the three copies in sync

The list now lives in three places: the reexport export block in src/FastAlmostBandedMatrices.jl, REEXPORTED_API in test/qa/qa.jl, and the docs section. The Core testset "Reexported BandedMatrices API" previously checked only the exports; it now also parses REEXPORTED_API out of test/qa/qa.jl and the role bullets out of docs/src/api.md and asserts all three are the same set. Both file reads are guarded by isfile, so the test degrades gracefully if the suite is run from a tree without docs/.

No source change, no behaviour change, no version bump.

Verified

• Pkg.test() (Core group), Julia 1.11.8 / macOS aarch64: 80 pass, 2 broken, 0 fail (was 76 pass before the 4 new sync assertions)
• GROUP=QA Pkg.test(): alloc_tests.jl 11 pass, qa.jl 18 pass / 2 broken / 0 fail (the 2 broken are the pre-existing aqua_broken = (:ambiguities,) and ei_broken = (:no_implicit_imports,))
• Runic --check clean over the repo
• Both external doc links return 200

Docs were not built locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ

[ChrisRackauckas]

Pushed 3f552b7 to fix the three Windows lanes.

Cause. Git checks the repo out with CRLF on Windows, and the docs section was located with a regex anchored on \n\nThese names are owned, which cannot match \r\n\r\n. match returned nothing, @test section !== nothing failed, and the next line then errored dereferencing nothing — which is the 1 failed, 1 errored pair in the log. Confirmed directly: the old regex run against a CRLF copy of docs/src/api.md returns nothing.

Fix.

• Both files are read through a helper that normalises \r\n and bare \r to \n before anything is matched, so nothing depends on the checkout's line endings.
• The docs section is now located structurally instead of by prose: from the ## Reexported from BandedMatrices.jl heading to the next ## heading (or EOF), taking the first contiguous run of - bullets. That run is the reexported names; the second bullet list in the same section is the deliberate exclusions and must not be picked up. Ordinary prose edits can no longer break the check.
• Every lookup reports what it looked for and where before failing (file, heading/pattern, and for a real drift the symmetric difference against the exports), and each result is guarded so a failed lookup cannot cascade into an error.

Kept the parse rather than downgrading to "the docs mention each name". Containment alone would not catch a name that appears only in the exclusions list, nor a stale name left in the docs after it was dropped from the exports — which is exactly the drift this test exists to catch.

Verified locally (Julia 1.11.8, macOS aarch64):

• Pkg.test() Core: 81 pass, 2 broken, 0 fail
• the extracted sync block against a synthetic CRLF copy of docs/src/api.md + test/qa/qa.jl: 5/5 pass (and 5/5 on the LF originals)
• a deliberately drifted CRLF copy with brandn removed from the docs bullets fails as intended, with only_in_exports = Set([:brandn])
• Runic --check clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ