Merge pull request #331 from abhro/docs

Update documentation

Author: aplavin

.github/workflows/Documenter.yml

@@ -9,20 +9,22 @@ on:
     tags: '*'
 jobs:
   docs:
+    name: Documentation
     permissions:
       contents: write
       statuses: write
-    name: Documentation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@v2
         with:
-          version: '1'
+          version: '1.10'
+      - uses: julia-actions/cache@v2
       - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+        shell: julia --color=yes --project=docs {0}
+        run: 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy
+        run: julia --color=yes --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia --project=docs/ docs/make.jl

docs/Project.toml

@@ -2,7 +2,12 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
+
+[sources]
+StructArrays = {path = ".."}
 
 [compat]
-Documenter = "0.27"
+Documenter = "1"
 PooledArrays = "1"
+StaticArrays = "1"

docs/make.jl

@@ -1,5 +1,3 @@
-push!(LOAD_PATH, dirname(@__DIR__))
-
 using Documenter
 using StructArrays
 
@@ -13,7 +11,8 @@ makedocs(
             "Some counterintuitive behaviors"=>"counterintuitive.md",
             "Advanced techniques"=>"advanced.md",
             "Index"=>"reference.md",
-            ]
+            ],
+    warnonly = [:missing_docs],
 )
 
 # Documenter can also automatically deploy documentation to gh-pages.

docs/src/advanced.md

@@ -66,13 +66,13 @@ StructArrays provides a function `StructArrays.append!!(dest, src)` (unexported)
 
 `StructArrays.append!!` works like `append!(dest, src)` if `dest` can contain all element types in `src` iterator; i.e., it _mutates_ `dest` in-place:
 
-```julia
+```julia-repl
 julia> dest = StructVector((a=[1], b=[2]))
-1-element StructArray(::Array{Int64,1}, ::Array{Int64,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,Int64}}:
+1-element StructArray(::Vector{Int64}, ::Vector{Int64}) with eltype NamedTuple{(:a, :b),Tuple{Int64,Int64}}:
  (a = 1, b = 2)
 
 julia> StructArrays.append!!(dest, [(a = 3, b = 4)])
-2-element StructArray(::Array{Int64,1}, ::Array{Int64,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,Int64}}:
+2-element StructArray(::Vector{Int64}, ::Vector{Int64}) with eltype NamedTuple{(:a, :b),Tuple{Int64,Int64}}:
  (a = 1, b = 2)
  (a = 3, b = 4)
 
@@ -82,9 +82,9 @@ true
 
 Unlike `append!`, `append!!` can also _widen_ element type of `dest` array:
 
-```julia
+```julia-repl
 julia> StructArrays.append!!(dest, [(a = missing, b = 6)])
-3-element StructArray(::Array{Union{Missing, Int64},1}, ::Array{Int64,1}) with eltype NamedTuple{(:a, :b),Tuple{Union{Missing, Int64},Int64}}:
+3-element StructArray(::Vector{Union{Missing, Int64}}, ::Vector{Int64}) with eltype NamedTuple{(:a, :b),Tuple{Union{Missing, Int64},Int64}}:
  NamedTuple{(:a, :b),Tuple{Union{Missing, Int64},Int64}}((1, 2))
  NamedTuple{(:a, :b),Tuple{Union{Missing, Int64},Int64}}((3, 4))
  NamedTuple{(:a, :b),Tuple{Union{Missing, Int64},Int64}}((missing, 6))

docs/src/counterintuitive.md

@@ -1,3 +1,6 @@
+```@meta
+DocTestSetup = :(using StructArrays)
+```
 # Some counterintuitive behaviors
 
 When created from parent arrays representing each field of the final `struct`, StructArrays creates a "view" which
@@ -13,7 +16,7 @@ These issues are elucidated below.
 
 For this demonstration, throughout we'll use this mutable struct:
 
-```jldoctest counter1; setup=:(using StructArrays)
+```jldoctest counter1
 julia> mutable struct Foo{T}
            a::T
            b::T
@@ -181,7 +184,7 @@ None of the changes to `soa` "propagated" to `aos`. This is because a StructArra
 ## Broadcasted assignment for array entries
 
 Broadcasted in-place assignment can also behave counterintuitively for StructArrays.
-```jldoctest; setup=:(using StructArrays)
+```jldoctest
 julia> using StaticArrays   # for FieldVector
 
 julia> mutable struct Bar{T} <: FieldVector{2,T}

docs/src/examples.md

@@ -1,20 +1,20 @@
 ## Example usage to store complex numbers
 
-```julia
+```julia-repl
 julia> using StructArrays, Random
 
 julia> Random.seed!(4);
 
 julia> s = StructArray{ComplexF64}((rand(2,2), rand(2,2)))
-2×2 StructArray(::Array{Float64,2}, ::Array{Float64,2}) with eltype Complex{Float64}:
+2×2 StructArray(::Matrix{Float64}, ::Matrix{Float64}) with eltype Complex{Float64}:
  0.680079+0.625239im   0.92407+0.267358im
  0.874437+0.737254im  0.929336+0.804478im
 
 julia> s[1, 1]
 0.680079235935741 + 0.6252391193298537im
 
 julia> s.re
-2×2 Array{Float64,2}:
+2×2 Matrix{Float64}:
  0.680079  0.92407
  0.874437  0.929336
 
@@ -24,39 +24,39 @@ julia> StructArrays.components(s) # obtain all field arrays as a named tuple
 
 Note that the same approach can be used directly from an `Array` of complex numbers:
 
-```julia
+```julia-repl
 julia> StructArray([1+im, 3-2im])
-2-element StructArray(::Array{Int64,1}, ::Array{Int64,1}) with eltype Complex{Int64}:
+2-element StructArray(::Vector{Int64}, ::Vector{Int64}) with eltype Complex{Int64}:
  1 + 1im
  3 - 2im
 ```
 
 ## Example usage to store a data table
 
-```julia
+```julia-repl
 julia> t = StructArray((a = [1, 2], b = ["x", "y"]))
-2-element StructArray(::Array{Int64,1}, ::Array{String,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
+2-element StructArray(::Vector{Int64}, ::Vector{String}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
  (a = 1, b = "x")
  (a = 2, b = "y")
 
 julia> t[1]
 (a = 1, b = "x")
 
 julia> t.a
-2-element Array{Int64,1}:
+2-element Vector{Int64}:
  1
  2
 
 julia> push!(t, (a = 3, b = "z"))
-3-element StructArray(::Array{Int64,1}, ::Array{String,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
+3-element StructArray(::Vector{Int64}, ::Vector{String}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
  (a = 1, b = "x")
  (a = 2, b = "y")
  (a = 3, b = "z")
 ```
 
 ## Example usage with StaticArray elements
 
-```julia
+```julia-repl
 julia> using StructArrays, StaticArrays
 
 julia> x = StructArray([SVector{2}(1,2) for i = 1:5])
@@ -84,4 +84,4 @@ julia> B = StructArray([SArray{Tuple{2,2,2}}(reshape(1:8,2,2,2)) for i = 1:5]);
 [:, :, 2] =
  5  7
  6  8
-```
+```

docs/src/index.md

@@ -46,14 +46,14 @@ StructArray(log(j+2.0*im) for j in 1:10)
 
 Another option is to create an uninitialized `StructArray` and then fill it with data. Just like in normal arrays, this is done with the `undef` syntax:
 
-```julia
+```julia-repl
 julia> s = StructArray{ComplexF64}(undef, 2, 2)
-2×2 StructArray(::Array{Float64,2}, ::Array{Float64,2}) with eltype Complex{Float64}:
+2×2 StructArray(::Matrix{Float64}, ::Matrix{Float64}) with eltype Complex{Float64}:
  6.91646e-310+6.91646e-310im  6.91646e-310+6.91646e-310im
  6.91646e-310+6.91646e-310im  6.91646e-310+6.91646e-310im
 
 julia> rand!(s)
-2×2 StructArray(::Array{Float64,2}, ::Array{Float64,2}) with eltype Complex{Float64}:
+2×2 StructArray(::Matrix{Float64}, ::Matrix{Float64}) with eltype Complex{Float64}:
  0.680079+0.874437im  0.625239+0.737254im
   0.92407+0.929336im  0.267358+0.804478im
 ```
@@ -88,7 +88,7 @@ julia> soa.re
 
 `StructArray`s supports using custom array types. It is always possible to pass field arrays of a custom type. The "custom array of `struct`s to `struct` of custom arrays" transformation will use the `similar` method of the custom array type. This can be useful when working on the GPU for example:
 
-```julia
+```julia-repl
 julia> using StructArrays, CuArrays
 
 julia> a = CuArray(rand(Float32, 10));
@@ -111,7 +111,7 @@ julia> StructArray{ComplexF32}((a, b))
 julia> c = CuArray(rand(ComplexF32, 10));
 
 julia> StructArray(c)
-10-element StructArray(::Array{Float32,1}, ::Array{Float32,1}) with eltype Complex{Float32}:
+10-element StructArray(::Vector{Float32}, ::Vector{Float32}) with eltype Complex{Float32}:
   0.7176411f0 + 0.864058f0im
    0.252609f0 + 0.14824867f0im
  0.26842773f0 + 0.9084332f0im
@@ -126,9 +126,9 @@ julia> StructArray(c)
 
 If you already have your data in a `StructArray` with field arrays of a given format (say plain `Array`) you can change them with `replace_storage`:
 
-```julia
+```julia-repl
 julia> s = StructArray([1.0+im, 2.0-im])
-2-element StructArray(::Array{Float64,1}, ::Array{Float64,1}) with eltype Complex{Float64}:
+2-element StructArray(::Vector{Float64}, ::Vector{Float64}) with eltype Complex{Float64}:
  1.0 + 1.0im
  2.0 - 1.0im
 
@@ -142,7 +142,7 @@ julia> replace_storage(CuArray, s)
 
 `StructArray`s also provides a `LazyRow` wrapper for lazy row iteration. `LazyRow(t, i)` does not materialize the i-th row but returns a lazy wrapper around it on which `getproperty` does the correct thing. This is useful when the row has many fields only some of which are necessary. It also allows changing columns in place.
 
-```julia
+```julia-repl
 julia> t = StructArray((a = [1, 2], b = ["x", "y"]));
 
 julia> LazyRow(t, 2).a
@@ -152,26 +152,26 @@ julia> LazyRow(t, 2).a = 123
 123
 
 julia> t
-2-element StructArray(::Array{Int64,1}, ::Array{String,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
+2-element StructArray(::Vector{Int64}, ::Vector{String}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
  (a = 1, b = "x")
  (a = 123, b = "y")
 ```
 
 To iterate in a lazy way one can simply iterate `LazyRows`:
 
-```julia
+```julia-repl
 julia> map(t -> t.b ^ t.a, LazyRows(t))
-2-element Array{String,1}:
+2-element Vector{String}:
  "x"
  "yy"
 ```
 
 ## Applying a function on each field array
 
-```julia
+```julia-repl
 julia> struct Foo
-       a::Int
-       b::String
+           a::Int
+           b::String
        end
 
 julia> s = StructArray([Foo(11, "a"), Foo(22, "b"), Foo(33, "c"), Foo(44, "d"), Foo(55, "e")]);

src/interface.jl

@@ -19,7 +19,7 @@ this will have fields with the same names and types as `T`.
 This can be overloaded for custom types if required, in which case
 [`StructArrays.component`](@ref) and [`StructArrays.createinstance`](@ref)
 should also be defined.
-    
+
 ```julia-repl
 julia> StructArrays.staticschema(Complex{Float64})
 NamedTuple{(:re, :im),Tuple{Float64,Float64}}

src/lazy.jl

@@ -20,7 +20,7 @@ julia> LazyRow(t, 2).a = 123
 123
 
 julia> t
-2-element StructArray(::Array{Int64,1}, ::Array{String,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
+2-element StructArray(::Vector{Int64}, ::Vector{String}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
  (a = 1, b = "x")
  (a = 123, b = "y")
 ```
@@ -68,7 +68,7 @@ An iterator of [`LazyRow`](@ref)s of `s`.
 
 ```julia-repl
 julia> map(t -> t.b ^ t.a, LazyRows(t))
-2-element Array{String,1}:
+2-element Vector{String}:
  "x"
  "yy"
 ```