Test docstrings (#239)

* Test docstrings

* simplify examples

Author: jishnub

Project.toml

@@ -10,17 +10,19 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 [compat]
 Aqua = "0.5, 0.6"
 ArrayLayouts = "1"
+Documenter = "0.27"
 FillArrays = "1"
 julia = "1.6"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Aqua", "Base64", "OffsetArrays", "SparseArrays", "StaticArrays", "Test", "Random"]
+test = ["Aqua", "Base64", "Documenter", "OffsetArrays", "SparseArrays", "StaticArrays", "Test", "Random"]

docs/src/man/blockarrays.md

@@ -23,10 +23,10 @@ julia> BlockArray(rand(4, 4), [2,2], [1,1,2])
 
 julia> block_array_sparse = BlockArray(sprand(4, 5, 0.7), [1,3], [2,3])
 2×2-blocked 4×5 BlockMatrix{Float64, Matrix{SparseMatrixCSC{Float64, Int64}}, Tuple{BlockedUnitRange{Vector{Int64}}, BlockedUnitRange{Vector{Int64}}}}:
- 0.0341601  0.374187  │  0.0118196  0.299058  0.0     
+ 0.0341601  0.374187  │  0.0118196  0.299058  0.0
  ---------------------┼-------------------------------
- 0.0945445  0.931115  │  0.0460428  0.0       0.0     
- 0.314926   0.438939  │  0.496169   0.0       0.0     
+ 0.0945445  0.931115  │  0.0460428  0.0       0.0
+ 0.314926   0.438939  │  0.496169   0.0       0.0
  0.12781    0.246862  │  0.732      0.449182  0.875096
 ```
 
@@ -77,17 +77,16 @@ julia> BlockArray(undef_blocks, SparseVector{Float64, Int}, [1,2])
 !!! warning
 
     Note that accessing an undefined block will throw an "access to undefined reference"-error!  If you create an array with undefined blocks, you _have_ to [initialize it block-wise](@ref setting_and_getting)); whole-array functions like `fill!` will not work:
-    
+
     ```julia
     julia> fill!(BlockArray{Float32}(undef_blocks, [1,2], [3,2]), 0)
     ERROR: UndefRefError: access to undefined reference
     …
     ```
-    
-    
+
 ## [Setting and getting blocks and values](@id setting_and_getting)
 
-A block can be set by  `block_array[Block(i...)] = v` or
+A block can be set by  `block_array[Block(i...)] = v`. The indexing may equivalently be carried out as
 `block_array[Block.(i)...]`.
 
 ```jldoctest block_array
@@ -98,24 +97,21 @@ julia> block_array = BlockArray{Float64}(undef_blocks, [1,2], [2,2])
  #undef  #undef  │  #undef  #undef
  #undef  #undef  │  #undef  #undef
 
-julia> block_array[Block(2,1)] = rand(2,2)
-2×2 Matrix{Float64}:
- 0.325977  0.218587
- 0.549051  0.894245
+julia> block_array[Block(2,1)] = reshape([1:4;], 2, 2);
 
 julia> block_array[Block(1),Block(1)] = [1 2];
 
 julia> block_array
 2×2-blocked 3×4 BlockMatrix{Float64}:
- 1.0       2.0       │  #undef  #undef
- ────────────────────┼────────────────
- 0.325977  0.218587  │  #undef  #undef
- 0.549051  0.894245  │  #undef  #undef
+ 1.0  2.0  │  #undef  #undef
+ ──────────┼────────────────
+ 1.0  3.0  │  #undef  #undef
+ 2.0  4.0  │  #undef  #undef
 ```
 
 Note that this will "take ownership" of the passed in array, that is, no copy is made.
 
-A block can be retrieved with `view(block_array, Block(i...))`, 
+A block can be retrieved with `view(block_array, Block(i...))`,
 or if a copy is desired, `block_array[Block(i...)]`:
 
 ```jldoctest block_array
@@ -171,10 +167,10 @@ An array can be repacked into a `BlockArray` with `BlockArray(array, block_sizes
 ```jl
 julia> block_array_sparse = BlockArray(sprand(4, 5, 0.7), [1,3], [2,3])
 2×2-blocked 4×5 BlockArray{Float64, 2, Matrix{SparseMatrixCSC{Float64, Int64}}, Tuple{BlockedUnitRange{Vector{Int64}}, BlockedUnitRange{Vector{Int64}}}}:
- 0.0341601  0.374187  │  0.0118196  0.299058  0.0     
+ 0.0341601  0.374187  │  0.0118196  0.299058  0.0
  ---------------------┼-------------------------------
- 0.0945445  0.931115  │  0.0460428  0.0       0.0     
- 0.314926   0.438939  │  0.496169   0.0       0.0     
+ 0.0945445  0.931115  │  0.0460428  0.0       0.0
+ 0.314926   0.438939  │  0.496169   0.0       0.0
  0.12781    0.246862  │  0.732      0.449182  0.875096
 ```
 

docs/src/man/pseudoblockarrays.md

@@ -10,7 +10,7 @@ end
 
 A `PseudoBlockArray` is similar to a [`BlockArray`](@ref) except the full array is stored
 contiguously instead of block by block. This means that is not possible to insert and retrieve
-blocks without copying data. On the other hand, converting a ``PseudoBlockArray` to the "full" underlying array is instead instant since
+blocks without copying data. On the other hand, converting a `PseudoBlockArray` to the "full" underlying array is instead instant since
 it can just return the wrapped array.
 
 When iteratively solving a set of equations with a gradient method the Jacobian typically has a block structure. It can be convenient
@@ -22,12 +22,12 @@ a direct solver using `Matrix`.
 Creating a `PseudoBlockArray` works in the same way as a `BlockArray`.
 
 ```jldoctest A
-julia> pseudo = PseudoBlockArray(rand(3,3), [1,2], [2,1])
-2×2-blocked 3×3 PseudoBlockMatrix{Float64}:
- 0.579862  0.0149088  │  0.839622
- ─────────────────────┼──────────
- 0.411294  0.520355   │  0.967143
- 0.972136  0.639562   │  0.131026
+julia> pseudo = PseudoBlockArray(reshape([1:9;], 3, 3), [1,2], [2,1])
+2×2-blocked 3×3 PseudoBlockMatrix{Int64}:
+ 1  4  │  7
+ ──────┼───
+ 2  5  │  8
+ 3  6  │  9
 ```
 
 This "takes ownership" of the passed in array so no copy of the array is made.
@@ -42,8 +42,8 @@ julia> PseudoBlockArray{Float32}(undef, [1,2], [3,2])
 2×2-blocked 3×5 PseudoBlockMatrix{Float32}:
  1.02295e-43  0.0          1.09301e-43  │  0.0          1.17709e-43
  ───────────────────────────────────────┼──────────────────────────
- 0.0          1.06499e-43  0.0          │  1.14906e-43  0.0        
- 1.05097e-43  0.0          1.13505e-43  │  0.0          1.1911e-43 
+ 0.0          1.06499e-43  0.0          │  1.14906e-43  0.0
+ 1.05097e-43  0.0          1.13505e-43  │  0.0          1.1911e-43
 ```
 We can also any other user defined array type that supports `similar`.
 
@@ -63,15 +63,15 @@ julia> copyto!(A, view(pseudo, Block(2, 1)));
 
 julia> A
 2×2 Matrix{Float64}:
- 0.411294  0.520355
- 0.972136  0.639562
+ 2.0  5.0
+ 3.0  6.0
 ```
 
 It is sometimes convenient to access an index in a certain block. We could of course write this as `A[Block(I,J)][i,j]` but the problem is that `A[Block(I,J)]` allocates its output so this type of indexing will be inefficient. Instead, it is possible to use the `A[BlockIndex((I,J), (i,j))]` indexing. Using the same block matrix `A` as above:
 
 ```jldoctest A
 julia> pseudo[BlockIndex((2,1), (2,2))]
-0.6395615996802734
+6
 ```
 
 The underlying array is accessed with `Array` just like for `BlockArray`.

src/abstractblockarray.jl

@@ -155,11 +155,6 @@ julia> A = BlockArray(v, [1,1], [2,1])
  ──────┼───
  2  4  │  6
 
-julia> Matrix.(collect(eachblock(A)))
-2×2 Matrix{Matrix{Int64}}:
- [1 3]  [5;;]
- [2 4]  [6;;]
-
 julia> sum.(eachblock(A))
 2×2 Matrix{Int64}:
  4  5

src/blockarray.jl

@@ -14,7 +14,7 @@ array-constructor-caller would like an uninitialized block array. See also
 undef_blocks (@ref), an alias for UndefBlocksInitializer().
 
 # Examples
-```julia
+```jldoctest; setup=:(using BlockArrays)
 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
 2×2-blocked 3×5 BlockMatrix{Float32}:
  #undef  #undef  #undef  │  #undef  #undef
@@ -33,11 +33,11 @@ type UndefBlocksInitializer (@ref), used in block array initialization to indica
 array-constructor-caller would like an uninitialized block array.
 
 # Examples
-```julia
+```jldoctest; setup=:(using BlockArrays)
 julia> BlockArray(undef_blocks, Matrix{Float32}, [1,2], [3,2])
 2×2-blocked 3×5 BlockMatrix{Float32}:
  #undef  #undef  #undef  │  #undef  #undef
- ------------------------┼----------------
+ ────────────────────────┼────────────────
  #undef  #undef  #undef  │  #undef  #undef
  #undef  #undef  #undef  │  #undef  #undef
 ```
@@ -220,23 +220,23 @@ This is an "inverse" of [`blocks`](@ref).
 # Examples
 ```jldoctest; setup = quote using BlockArrays end
 julia> arrays = permutedims(reshape([
-                  1ones(1, 3), 2ones(1, 2),
-                  3ones(2, 3), 4ones(2, 2),
+                  fill(1.0, 1, 3), fill(2.0, 1, 2),
+                  fill(3.0, 2, 3), fill(4.0, 2, 2),
               ], (2, 2)))
 2×2 Matrix{Matrix{Float64}}:
  [1.0 1.0 1.0]               [2.0 2.0]
  [3.0 3.0 3.0; 3.0 3.0 3.0]  [4.0 4.0; 4.0 4.0]
 
-julia> mortar(arrays)
+julia> M = mortar(arrays)
 2×2-blocked 3×5 BlockMatrix{Float64}:
  1.0  1.0  1.0  │  2.0  2.0
  ───────────────┼──────────
  3.0  3.0  3.0  │  4.0  4.0
  3.0  3.0  3.0  │  4.0  4.0
 
-julia> ans == mortar(
-                  (1ones(1, 3), 2ones(1, 2)),
-                  (3ones(2, 3), 4ones(2, 2)),
+julia> M == mortar(
+                  (fill(1.0, 1, 3), fill(2.0, 1, 2)),
+                  (fill(3.0, 2, 3), fill(4.0, 2, 2)),
               )
 true
 ```

src/pseudo_blockarray.jl

@@ -17,27 +17,24 @@ When iteratively solving a set of equations with a gradient method the Jacobian
 to use a `PseudoBlockArray` to build up the Jacobian block by block and then pass the resulting matrix to
 a direct solver using `Array`.
 
-```jldoctest
-julia> using BlockArrays, Random, SparseArrays
-
-julia> Random.seed!(12345);
-
-julia> A = PseudoBlockArray(rand(2,3), [1,1], [2,1])
-2×2-blocked 2×3 PseudoBlockMatrix{Float64}:
- 0.944791  0.339612  │  0.322501
- ────────────────────┼──────────
- 0.866895  0.136117  │  0.252549
-
-julia> A = PseudoBlockArray(sprand(6, 0.5), [3,2,1])
-3-blocked 6-element PseudoBlockVector{Float64, SparseVector{Float64, Int64}, Tuple{BlockedUnitRange{Vector{Int64}}}}:
- 0.0
- 0.0
- 0.26755021483368013
- ───────────────────
- 0.0
- 0.11848853125656122
- ───────────────────
- 0.0
+# Examples
+```jldoctest; setup=:(using BlockArrays)
+julia> PseudoBlockArray(reshape([1:6;], 2, 3), [1,1], [2,1])
+2×2-blocked 2×3 PseudoBlockMatrix{Int64}:
+ 1  3  │  5
+ ──────┼───
+ 2  4  │  6
+
+julia> PseudoBlockArray([1:6;], [3,2,1])
+3-blocked 6-element PseudoBlockVector{Int64}:
+ 1
+ 2
+ 3
+ ─
+ 4
+ 5
+ ─
+ 6
 ```
 """
 struct PseudoBlockArray{T, N, R<:AbstractArray{T,N}, BS<:NTuple{N,AbstractUnitRange{Int}}} <: AbstractBlockArray{T, N}

test/runtests.jl

@@ -5,6 +5,11 @@ using Aqua
     Aqua.test_all(BlockArrays, ambiguities=false)
 end
 
+using Documenter
+@testset "docstrings" begin
+    doctest(BlockArrays)
+end
+
 include("test_blockindices.jl")
 include("test_blockarrays.jl")
 include("test_blockviews.jl")