diff --git a/docs/make.jl b/docs/make.jl index c507af4..438b82e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,5 +1,12 @@ using Documenter, FastAlmostBandedMatrices +DocMeta.setdocmeta!( + FastAlmostBandedMatrices, + :DocTestSetup, + :(using FastAlmostBandedMatrices), + recursive = true, +) + makedocs(; sitename = "FastAlmostBandedMatrices.jl", authors = "Avik Pal et al.", diff --git a/docs/src/api.md b/docs/src/api.md index 8538891..b181861 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -42,11 +42,8 @@ to be imported separately: - Querying them: `bandwidth`, `bandwidths`, `colrange`, `rowrange` - Errors: `BandError` -These names are owned and documented by +These names are defined and documented by [BandedMatrices.jl](https://juliaLinearAlgebra.github.io/BandedMatrices.jl/stable/). -FastAlmostBandedMatrices.jl only re-exports them; it does not document them and does not -define their behaviour, so BandedMatrices.jl's own documentation is the reference for what -each one does. Anything else from BandedMatrices.jl must be imported from BandedMatrices.jl directly. In particular, the following are deliberately **not** reexported: @@ -60,11 +57,17 @@ In particular, the following are deliberately **not** reexported: the qualified form. - `symrcm`, a sparse-matrix reordering unrelated to this package. -`Band` and `BandError` have no docstring upstream in BandedMatrices.jl, so they are listed -in the `api_docs_kwargs` ignore list in `test/qa/qa.jl` rather than documented here; that -docstring is owed by BandedMatrices.jl. Every other reexported name above carries its own +The `Band` and `BandError` types are defined by +[BandedMatrices.jl](https://juliaLinearAlgebra.github.io/BandedMatrices.jl/stable/), and +FastAlmostBandedMatrices.jl documents their public bindings here because they are part of +its documented construction workflow. Every other reexported name above carries its upstream docstring, reachable from the REPL help mode. +```@docs +Band +BandError +``` + The list above is kept in sync with the reexport `export` block in `src/FastAlmostBandedMatrices.jl` and with `REEXPORTED_API` in `test/qa/qa.jl`, and the Core test suite asserts that all three agree. diff --git a/src/FastAlmostBandedMatrices.jl b/src/FastAlmostBandedMatrices.jl index 20119d8..f01eb59 100644 --- a/src/FastAlmostBandedMatrices.jl +++ b/src/FastAlmostBandedMatrices.jl @@ -15,10 +15,72 @@ import MatrixFactorizations # The BandedMatrices.jl surface that FastAlmostBandedMatrices reexports (see the second # `export` below), so that `using FastAlmostBandedMatrices` on its own is enough to build # the `bands` argument of an `AlmostBandedMatrix`, populate it, and query its band -# structure. Everything stays owned and documented upstream in BandedMatrices.jl. +# structure. The BandedMatrices.jl definitions remain canonical; the two docstrings below +# document their public bindings in this module. using BandedMatrices: Band, BandError, BandRange, BandedMatrix, band, bandrange, bandwidth, bandwidths, brand, brandn, colrange, rowrange +""" + Band(i) + +Index selector for the diagonal at offset `i` of a banded matrix. `Band(0)` selects the +main diagonal, positive offsets select superdiagonals, and negative offsets select +subdiagonals. + +# Fields + +- `i::Int`: Diagonal offset from the main diagonal. + +# Arguments + +- `i::Int`: Diagonal offset to select. + +# Examples + +```jldoctest +julia> A = BandedMatrix(0 => 1:3, 1 => 4:5); + +julia> A[Band(0)] == [1, 2, 3] +true + +julia> A[Band(1)] == [4, 5] +true +``` +""" +Band + +""" + BandError(A, i) + BandError(A, (k, j)) + BandError(A) + +Exception thrown when an operation accesses diagonal offset `i` outside the stored lower +and upper bandwidths of `A`. + +# Fields + +- `A::AbstractMatrix`: Matrix whose band structure rejects the access. +- `i::Int`: Requested diagonal offset, with positive offsets above and negative offsets + below the main diagonal. + +# Arguments + +- `A::AbstractMatrix`: Matrix whose band structure is being accessed. +- `i::Int`: Requested diagonal offset. +- `(k, j)::Tuple{Int, Int}`: Matrix coordinates from which the diagonal offset `j - k` is + computed. + +# Examples + +```jldoctest +julia> A = BandedMatrix(0 => 1:3); + +julia> BandError(A, 1) isa BandError +true +``` +""" +BandError + import ArrayLayouts: MemoryLayout, sublayout, MatLdivVec, materialize!, triangularlayout, triangulardata, colsupport, rowsupport, _qr, _qr!, _factorize, muladd!, QRPackedQLayout, AdjQRPackedQLayout diff --git a/test/qa/qa.jl b/test/qa/qa.jl index 6a9e2ce..84a5f75 100644 --- a/test/qa/qa.jl +++ b/test/qa/qa.jl @@ -12,9 +12,6 @@ const REEXPORTED_API = ( run_qa( FastAlmostBandedMatrices; reexports_allow = REEXPORTED_API, - # `Band` and `BandError` are reexported but carry no docstring upstream in - # BandedMatrices.jl, so the public-API docstring check has nothing to find for them. - api_docs_kwargs = (; ignore = (:Band, :BandError)), ei_kwargs = (; # Non-public names this package legitimately extends/uses from upstream: # ArrayLayouts MatLdivVec/sublayout/triangulardata/triangularlayout/_qr/_qr!/