Fix docstrings, and make docs runnable (#155)

* fix docstrings, and make docs runnable

* don't track docs/build

Author: jishnub

.gitignore

@@ -1,3 +1,4 @@
 
 .DS_Store
 Manifest.toml
+docs/build

docs/Project.toml

@@ -1,5 +1,11 @@
 [deps]
+BlockArrays = "8e7c35d0-a365-5155-bbbb-fb81a777f24e"
+BlockBandedMatrices = "ffab5731-97b5-5995-9138-79e8c1846df0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 
 [compat]
-Documenter = "= 0.27"
+BlockArrays = "0.16"
+Documenter = "0.27"
+FillArrays = "1"

docs/make.jl

@@ -1,5 +1,7 @@
 using Documenter, BlockBandedMatrices
 
+DocMeta.setdocmeta!(BlockBandedMatrices, :DocTestSetup, :(using BlockBandedMatrices))
+
 makedocs(
     modules = [BlockBandedMatrices],
     sitename = "BlockBandedMatrices.jl",

docs/src/index.md

@@ -5,10 +5,11 @@
 
 ```@docs
 BlockBandedMatrix
-```
-
-```@docs
+BlockBandedMatrix(::AbstractMatrix, ::AbstractVector{Int}, ::AbstractVector{Int}, ::NTuple{2,Int})
+BlockBandedMatrix(::AbstractMatrix, ::NTuple{2,Int})
+BlockBandedMatrix{T}(::UndefInitializer, ::AbstractVector{Int}, ::AbstractVector{Int}, ::NTuple{2,Int})
 BandedBlockBandedMatrix
+BandedBlockBandedMatrix{T}(::UndefInitializer, ::AbstractVector{Int}, ::AbstractVector{Int}, ::NTuple{2,Int}, ::NTuple{2,Int})
 ```
 
 
@@ -41,7 +42,7 @@ of row and column blocks, then `A` has zero structure
   a_21 a_22 │  ⋅    ⋅
   ──────────┼──────────
   a_31 a_32 │ a_33 a_34
-  a_41 a_42 │ a_43 a_44  
+  a_41 a_42 │ a_43 a_44
   ──────────┼──────────
    ⋅    ⋅   │ a_53 a_54
    ⋅    ⋅   │ a_63 a_64 ]
@@ -69,7 +70,7 @@ of row and column blocks, then `A` has zero structure
   a_21 a_22 │  ⋅    ⋅
   ──────────┼──────────
   a_31  ⋅   │ a_33  ⋅
-  a_41 a_42 │ a_43 a_44  
+  a_41 a_42 │ a_43 a_44
   ──────────┼──────────
    ⋅    ⋅   │ a_53  ⋅
    ⋅    ⋅   │ a_63 a_64 ]
@@ -78,7 +79,7 @@ and is stored in memory via `A.data` as a `PseudoBlockMatrix`, which has block s
 2 x 2, containing entries:
 ```julia
 [a_11 a_22 │ a_33 a_44
- a_21  ×   │ a_43  ×  
+ a_21  ×   │ a_43  ×
  ──────────┼──────────
  a_31 a_42 │ a_53 a_64
  a_41  ×   │ a_63  ×   ]

src/AbstractBlockBandedMatrix.jl

@@ -78,7 +78,7 @@ Returns the lower blockbandwidth (`i==1`) or the upper blockbandwidth (`i==2`).
 blockbandwidth(A, k::Integer) = blockbandwidths(A)[k]
 
 """
-    bandrange(A)
+    blockbandrange(A)
 
 Returns the range `-blockbandwidth(A,1):blockbandwidth(A,2)`.
 """

src/BandedBlockBandedMatrix.jl

@@ -62,23 +62,33 @@ BandedBlockBandedMatrix{T,B}(::UndefInitializer, rblocksizes::AbstractVector{Int
 
 BandedBlockBandedMatrix{T}(::UndefInitializer, axes::NTuple{2,AbstractUnitRange{Int}}, lu::NTuple{2,Int}, λμ::NTuple{2,Int}) where T =
     _BandedBlockBandedMatrix(PseudoBlockMatrix{T}(undef, _bbb_data_axes(axes[2],lu,λμ)), axes[1], lu, λμ)
+"""
+    BandedBlockBandedMatrix{T}(undef, rows, cols, (l, u), (λ, μ))
+
+Return an unitialized `BandedBlockBandedMatrix` having `eltype` `T`,
+with block-bandwidths `(l,u)` and where `A[Block(K,J)]` is a
+`BandedMatrix{T}` of size `rows[K]×cols[J]` with bandwidths `(λ,μ)`.
+"""
 BandedBlockBandedMatrix{T}(::UndefInitializer, rblocksizes::AbstractVector{Int}, cblocksizes::AbstractVector{Int}, lu::NTuple{2,Int}, λμ::NTuple{2,Int}) where T =
     BandedBlockBandedMatrix{T}(undef, (blockedrange(rblocksizes),blockedrange(cblocksizes)), lu, λμ)
 
 
 """
-    BandedBlockBandedMatrix{T}(M::Union{UndefInitializer,UniformScaling,AbstractMatrix},
+    BandedBlockBandedMatrix(M::Union{UniformScaling,AbstractMatrix},
                                rows, cols, (l, u), (λ, μ))
 
-returns a `sum(rows)`×`sum(cols)` banded-block-banded matrix `A` having elements of
-type `T`, with block-bandwidths `(l,u)` and where `A[Block(K,J)]` is a
-`BandedMatrix{T}` of size `rows[K]`×`cols[J]` with bandwidths `(λ,μ)`.
+Return a `sum(rows) × sum(cols)` banded-block-banded matrix `A`,
+with block-bandwidths `(l,u)` and where `A[Block(K,J)]` is a
+`BandedMatrix` of size `rows[K]`×`cols[J]` with bandwidths `(λ,μ)`.
+The structural non-zero elements of the returned matrix corresponds to those of `M`.
 
 # Examples
 
 ```jldoctest
+julia> using LinearAlgebra, FillArrays
+
 julia> BandedBlockBandedMatrix(I, [3,4,3], [3,4,3], (1,1), (1,1))
-3×3-blocked 10×10 BandedBlockBandedMatrix{Bool,BlockArrays.PseudoBlockArray{Bool,2,Array{Bool,2},Tuple{BlockArrays.BlockedUnitRange{Array{Int64,1}},BlockArrays.BlockedUnitRange{Array{Int64,1}}}},BlockArrays.BlockedUnitRange{Array{Int64,1}}}:
+3×3-blocked 10×10 BandedBlockBandedMatrix{Bool, BlockArrays.PseudoBlockMatrix{Bool, Matrix{Bool}, Tuple{BlockArrays.BlockedUnitRange{Vector{Int64}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}:
  1  0  ⋅  │  0  0  ⋅  ⋅  │  ⋅  ⋅  ⋅
  0  1  0  │  0  0  0  ⋅  │  ⋅  ⋅  ⋅
  ⋅  0  1  │  ⋅  0  0  0  │  ⋅  ⋅  ⋅
@@ -93,7 +103,7 @@ julia> BandedBlockBandedMatrix(I, [3,4,3], [3,4,3], (1,1), (1,1))
  ⋅  ⋅  ⋅  │  ⋅  0  0  0  │  ⋅  0  1
 
 julia> BandedBlockBandedMatrix(Ones{Int}(10,13), [3,4,3], [4,5,4], (1,1), (1,1))
-3×3-blocked 10×13 BandedBlockBandedMatrix{Int64,BlockArrays.PseudoBlockArray{Int64,2,Array{Int64,2},Tuple{BlockArrays.BlockedUnitRange{Array{Int64,1}},BlockArrays.BlockedUnitRange{Array{Int64,1}}}},BlockArrays.BlockedUnitRange{Array{Int64,1}}}:
+3×3-blocked 10×13 BandedBlockBandedMatrix{Int64, BlockArrays.PseudoBlockMatrix{Int64, Matrix{Int64}, Tuple{BlockArrays.BlockedUnitRange{Vector{Int64}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}:
  1  1  ⋅  ⋅  │  1  1  ⋅  ⋅  ⋅  │  ⋅  ⋅  ⋅  ⋅
  1  1  1  ⋅  │  1  1  1  ⋅  ⋅  │  ⋅  ⋅  ⋅  ⋅
  ⋅  1  1  1  │  ⋅  1  1  1  ⋅  │  ⋅  ⋅  ⋅  ⋅

src/BlockSkylineMatrix.jl

@@ -120,6 +120,12 @@ struct BlockSkylineMatrix{T, DATA<:AbstractVector{T}, BS<:BlockSkylineSizes} <:
     end
 end
 
+"""
+    BlockBandedMatrix
+
+A `BlockBandedMatrix` is a subtype of `BlockMatrix` of `BlockArrays.jl` whose
+layout of non-zero blocks is banded.
+"""
 const BlockBandedMatrix{T} = BlockSkylineMatrix{T, Vector{T}, BlockBandedSizes}
 
 # Auxiliary outer constructors
@@ -149,8 +155,10 @@ lengths `rows` and `cols`, respectively, for ragged bands.
 # Examples
 
 ```jldoctest
+julia> using LinearAlgebra, FillArrays
+
 julia> BlockSkylineMatrix(I, [2,3,4], [1,2,3], ([2,0,1],[1,1,1]))
-3×3-blocked 9×6 BlockSkylineMatrix{Bool,Array{Bool,1},BlockBandedMatrices.BlockSkylineSizes{Tuple{BlockArrays.BlockedUnitRange{Array{Int64,1}},BlockArrays.BlockedUnitRange{Array{Int64,1}}},Array{Int64,1},Array{Int64,1},BandedMatrices.BandedMatrix{Int64,Array{Int64,2},Base.OneTo{Int64}},Array{Int64,1}}}:
+3×3-blocked 9×6 BlockSkylineMatrix{Bool, Vector{Bool}, BlockBandedMatrices.BlockSkylineSizes{Tuple{BlockArrays.BlockedUnitRange{Vector{Int64}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}, Vector{Int64}, Vector{Int64}, BandedMatrices.BandedMatrix{Int64, Matrix{Int64}, Base.OneTo{Int64}}, Vector{Int64}}}:
  1  │  0  0  │  ⋅  ⋅  ⋅
  0  │  1  0  │  ⋅  ⋅  ⋅
  ───┼────────┼─────────
@@ -164,7 +172,7 @@ julia> BlockSkylineMatrix(I, [2,3,4], [1,2,3], ([2,0,1],[1,1,1]))
  0  │  ⋅  ⋅  │  0  0  0
 
 julia> BlockSkylineMatrix(Ones(9,6), [2,3,4], [1,2,3], ([2,0,1],[1,1,1]))
-3×3-blocked 9×6 BlockSkylineMatrix{Float64,Array{Float64,1},BlockBandedMatrices.BlockSkylineSizes{Tuple{BlockArrays.BlockedUnitRange{Array{Int64,1}},BlockArrays.BlockedUnitRange{Array{Int64,1}}},Array{Int64,1},Array{Int64,1},BandedMatrices.BandedMatrix{Int64,Array{Int64,2},Base.OneTo{Int64}},Array{Int64,1}}}:
+3×3-blocked 9×6 BlockSkylineMatrix{Float64, Vector{Float64}, BlockBandedMatrices.BlockSkylineSizes{Tuple{BlockArrays.BlockedUnitRange{Vector{Int64}}, BlockArrays.BlockedUnitRange{Vector{Int64}}}, Vector{Int64}, Vector{Int64}, BandedMatrices.BandedMatrix{Int64, Matrix{Int64}, Base.OneTo{Int64}}, Vector{Int64}}}:
  1.0  │  1.0  1.0  │   ⋅    ⋅    ⋅
  1.0  │  1.0  1.0  │   ⋅    ⋅    ⋅
  ─────┼────────────┼───────────────
@@ -186,6 +194,13 @@ BlockSkylineMatrix
 @inline BlockSkylineMatrix{T}(::UndefInitializer, axes::NTuple{2,AbstractUnitRange{Int}}, lu::NTuple{2, AbstractVector{Int}}) where T =
     BlockSkylineMatrix{T}(undef, BlockSkylineSizes(axes, lu...))
 
+"""
+    BlockBandedMatrix{T}(undef, rows::AbstractVector{Int}, cols::AbstractVector{Int},
+                        (l,u)::NTuple{2,Int})
+
+Return an unitialized `sum(rows) × sum(cols)` `BlockBandedMatrix` having `eltype` `T`,
+with `rows` by `cols` blocks and `(l,u)` as the block-bandwidth.
+"""
 @inline BlockBandedMatrix{T}(::UndefInitializer, rdims::AbstractVector{Int}, cdims::AbstractVector{Int}, lu::NTuple{2, Int}) where T =
     BlockSkylineMatrix{T}(undef, BlockBandedSizes(rdims, cdims, lu...))
 
@@ -257,10 +272,78 @@ BlockBandedMatrix{T}(A::Union{AbstractMatrix,UniformScaling},
 BlockSkylineMatrix(A::Union{AbstractMatrix,UniformScaling},
                         rdims::AbstractVector{Int}, cdims::AbstractVector{Int},
                         lu::NTuple{2,AbstractVector{Int}}) = BlockSkylineMatrix{eltype(A)}(A, rdims, cdims, lu)
+
+
+"""
+    BlockBandedMatrix(A::Union{AbstractMatrix,UniformScaling},
+                        rows::AbstractVector{Int}, cols::AbstractVector{Int},
+                        (l,u)::NTuple{2,Int})
+
+Return a `sum(rows) × sum(cols)` `BlockBandedMatrix`, with `rows` by `cols` blocks,
+with `(l,u)` as the block-bandwidth.
+The structural non-zero entries are equal to the corresponding indices of `A`.
+
+# Examples
+```jldoctest
+julia> using LinearAlgebra, FillArrays
+
+julia> l,u = 0,1; # block bandwidths
+
+julia> nrowblk, ncolblk = 3, 3; # number of row/column blocks
+
+julia> rows = 1:nrowblk; cols = 1:ncolblk; # block sizes
+
+julia> BlockBandedMatrix(I, rows, cols, (l,u))
+3×3-blocked 6×6 BlockBandedMatrix{Bool}:
+ 1  │  0  0  │  ⋅  ⋅  ⋅
+ ───┼────────┼─────────
+ ⋅  │  1  0  │  0  0  0
+ ⋅  │  0  1  │  0  0  0
+ ───┼────────┼─────────
+ ⋅  │  ⋅  ⋅  │  1  0  0
+ ⋅  │  ⋅  ⋅  │  0  1  0
+ ⋅  │  ⋅  ⋅  │  0  0  1
+
+julia> BlockBandedMatrix(Ones(sum(rows),sum(cols)), rows, cols, (l,u))
+3×3-blocked 6×6 BlockBandedMatrix{Float64}:
+ 1.0  │  1.0  1.0  │   ⋅    ⋅    ⋅
+ ─────┼────────────┼───────────────
+  ⋅   │  1.0  1.0  │  1.0  1.0  1.0
+  ⋅   │  1.0  1.0  │  1.0  1.0  1.0
+ ─────┼────────────┼───────────────
+  ⋅   │   ⋅    ⋅   │  1.0  1.0  1.0
+  ⋅   │   ⋅    ⋅   │  1.0  1.0  1.0
+  ⋅   │   ⋅    ⋅   │  1.0  1.0  1.0
+```
+"""
 BlockBandedMatrix(A::Union{AbstractMatrix,UniformScaling},
                         rdims::AbstractVector{Int}, cdims::AbstractVector{Int},
                         lu::NTuple{2,Int}) = BlockBandedMatrix{eltype(A)}(A, rdims, cdims, lu)
 
+"""
+    BlockBandedMatrix(A::AbstractMatrix, (l,u)::NTuple{2,Int})
+
+Return a `BlockBandedMatrix` with block-bandwidths `(l,u)`, where the
+structural non-zero blocks correspond to those of `A`.
+
+Examples
+```jldoctest
+julia> using BlockArrays
+
+julia> B = BlockArray(ones(6,6), 1:3, 1:3);
+
+julia> BlockBandedMatrix(B, (1,1))
+3×3-blocked 6×6 BlockBandedMatrix{Float64}:
+ 1.0  │  1.0  1.0  │   ⋅    ⋅    ⋅
+ ─────┼────────────┼───────────────
+ 1.0  │  1.0  1.0  │  1.0  1.0  1.0
+ 1.0  │  1.0  1.0  │  1.0  1.0  1.0
+ ─────┼────────────┼───────────────
+  ⋅   │  1.0  1.0  │  1.0  1.0  1.0
+  ⋅   │  1.0  1.0  │  1.0  1.0  1.0
+  ⋅   │  1.0  1.0  │  1.0  1.0  1.0
+```
+"""
 BlockBandedMatrix(A::AbstractMatrix, lu::NTuple{2,Int}) = BlockBandedMatrix(A, BlockBandedSizes(axes(A), lu...))
 
 function convert(::Type{BlockSkylineMatrix}, A::AbstractMatrix)