Set up Documenter (#158)

* Set up Documenter

* more docs, add action

* more docs

* fix Documenter script

* typo

* add to LOAD_PATH

* move doctests to runtests.jl

* interpolate types into doctest strings

Author: simonbyrne

.github/workflows/Documenter.yml

@@ -0,0 +1,29 @@
+name: Documenter
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+    tags: '*'
+jobs:
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - run: |
+          julia --project -e '
+            using Pkg
+            Pkg.instantiate()'
+          julia --project=docs -e '
+            using Pkg
+            Pkg.instantiate()'
+      - run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

Project.toml

@@ -14,10 +14,11 @@ Tables = "1"
 julia = "1"
 
 [extras]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 WeakRefStrings = "ea10d353-3f73-51f8-a26c-33c1cb351aa5"
 
 [targets]
-test = ["Test", "OffsetArrays", "PooledArrays", "WeakRefStrings"]
+test = ["Test", "OffsetArrays", "PooledArrays", "WeakRefStrings", "Documenter"]

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"

docs/make.jl

@@ -0,0 +1,18 @@
+push!(LOAD_PATH, dirname(@__DIR__))
+
+using Documenter
+using StructArrays
+
+makedocs(
+    sitename = "StructArrays",
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
+    modules = [StructArrays]
+)
+
+# Documenter can also automatically deploy documentation to gh-pages.
+# See "Hosting Documentation" and deploydocs() in the Documenter manual
+# for more information.
+deploydocs(
+    repo = "github.com/JuliaArrays/StructArrays.jl.git",
+    push_preview = true,
+)

docs/src/index.md

@@ -0,0 +1,54 @@
+# StructArrays.jl
+
+
+```@meta
+CurrentModule = StructArrays
+```
+
+# Type
+
+```@docs
+StructArray
+```
+
+# Constructors
+
+```@docs
+StructArray(tup::Union{Tuple,NamedTuple})
+StructArray(::Base.UndefInitializer, sz::Dims)
+StructArray(v)
+collect_structarray
+```
+
+# Accessors
+
+```@docs
+fieldarrays
+```
+
+# Lazy iteration
+
+```@docs
+LazyRow
+LazyRows
+```
+
+# Advanced APIs
+
+```@docs
+StructArrays.append!!
+StructArrays.replace_storage
+StructArrays.staticschema
+StructArrays.createinstance
+```
+
+# Internals
+
+```@docs
+StructArrays.get_ith
+StructArrays.map_params
+StructArrays._map_params
+StructArrays.buildfromschema
+StructArrays.bypass_constructor
+StructArrays.iscompatible
+```

src/collect.jl

@@ -27,7 +27,7 @@ _axes(itr, ::Base.HasLength) = (Base.OneTo(length(itr)),)
 _axes(itr, ::Base.HasShape) = axes(itr)
 
 """
-`collect_structarray(itr; initializer = default_initializer)`
+    collect_structarray(itr; initializer = default_initializer)
 
 Collects `itr` into a `StructArray`. The user can optionally pass a `initializer`, that is to say
 a function `(S, d) -> v` that associates to a type and a size an array of eltype `S`
@@ -128,18 +128,18 @@ function _widenarray(dest::AbstractArray, i, ::Type{T}) where T
 end
 
 """
-`append!!(dest, itr) -> dest′`
-
-Try to append `itr` into a vector `dest`.  Widen element type of
-`dest` if it cannot hold the elements of `itr`.  That is to say,
+    dest = StructArrays.append!!(dest, itr)
 
+Try to append `itr` into a vector `dest`, widening the element type of `dest` if
+it cannot hold the elements of `itr`. That is to say,
 ```julia
 vcat(dest, StructVector(itr)) == append!!(dest, itr)
 ```
+holds. Note that the `dest` argument may or may not be the same object as the
+returned value.
 
-holds.  Note that `dest′` may or may not be the same object as `dest`.
-The state of `dest` is unpredictable after `append!!`
-is called (e.g., it may contain just half of the elements from `itr`).
+The state of `dest` is unpredictable after `append!!` is called (e.g., it may
+contain some, none or all the elements from `itr`).
 """
 append!!(dest::AbstractVector, itr) =
     _append!!(dest, itr, Base.IteratorSize(itr))

src/interface.jl

@@ -1,6 +1,21 @@
 const Tup = Union{Tuple, NamedTuple}
 const EmptyTup = Union{Tuple{}, NamedTuple{(), Tuple{}}}
 
+"""
+    StructArrays.staticschema(T)
+
+The default schema for an element type `T`. A schema is a `Tuple` or
+`NamedTuple` type containing the necessary fields to construct `T`. By default,
+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.createinstance`](@ref) should also be defined.
+
+```julia-repl
+julia> StructArrays.staticschema(Complex{Float64})
+NamedTuple{(:re, :im),Tuple{Float64,Float64}}
+```
+"""
 @generated function staticschema(::Type{T}) where {T}
     name_tuple = Expr(:tuple, [QuoteNode(f) for f in fieldnames(T)]...)
     type_tuple = Expr(:curly, :Tuple, [Expr(:call, :fieldtype, :T, i) for i in 1:fieldcount(T)]...)
@@ -9,6 +24,18 @@ end
 
 staticschema(::Type{T}) where {T<:Tup} = T
 
+"""
+    StructArrays.createinstance(T, args...)
+
+Construct an instance of type `T` from its backing representation. `args` here
+are the elements of the `Tuple` or `NamedTuple` type specified
+[`staticschema(T)`](@ref).
+
+```julia-repl
+julia> StructArrays.createinstance(Complex{Float64}, (re=1.0, im=2.0)...)
+1.0 + 2.0im
+```
+"""
 function createinstance(::Type{T}, args...) where {T}
     isconcretetype(T) ? bypass_constructor(T, args) : T(args...)
 end

src/lazy.jl

@@ -1,3 +1,30 @@
+"""
+    LazyRow(s::StructArray, i)
+
+A lazy representation of `s[i]`. `LazyRow(s, 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.
+
+See [`LazyRows`](@ref) to get an iterator of `LazyRow`s.
+
+# Examples
+
+```julia-repl
+julia> t = StructArray((a = [1, 2], b = ["x", "y"]));
+
+julia> LazyRow(t, 2).a
+2
+
+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}}:
+ (a = 1, b = "x")
+ (a = 123, b = "y")
+```
+"""
 struct LazyRow{T, N, C, I}
     columns::StructArray{T, N, C, I} # a `Columns` object
     index::I
@@ -29,6 +56,20 @@ iscompatible(::Type{<:LazyRow{R}}, ::Type{S}) where {R, S<:StructArray} = iscomp
 
 (s::ArrayInitializer)(::Type{<:LazyRow{T}}, d) where {T} = buildfromschema(typ -> s(typ, d), T)
 
+"""
+    LazyRows(s::StructArray)
+
+An iterator of [`LazyRow`](@ref)s of `s`.
+
+# Examples
+
+```julia-repl
+julia> map(t -> t.b ^ t.a, LazyRows(t))
+2-element Array{String,1}:
+ "x"
+ "yy"
+```
+"""
 struct LazyRows{T, N, C, I} <: AbstractArray{LazyRow{T, N, C, I}, N}
     columns::StructArray{T, N, C, I}
 end