Merge pull request #210 from SciML/docs

Build a proper documentation

Author: ChrisRackauckas

.github/workflows/Documentation.yml

@@ -0,0 +1,25 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -5,128 +5,4 @@
 [![Build status](https://badge.buildkite.com/5f39777d009ce94ef1dcf2a4881c68b9fbcaf6f69f1d8b8df2.svg)](https://buildkite.com/julialang/recursivearraytools-dot-jl)
 
 RecursiveArrayTools.jl is a set of tools for dealing with recursive arrays like
-arrays of arrays. The current functionality includes:
-
-### Types
-
-#### VectorOfArray
-
-```julia
-VectorOfArray(u::AbstractVector)
-```
-
-A `VectorOfArray` is an array which has the underlying data structure `Vector{AbstractArray{T}}`
-(but, hopefully, concretely typed!). This wrapper over such data structures allows one to lazily
-act like it's a higher-dimensional vector, and easily convert to different forms. The indexing
-structure is:
-
-```julia
-A[i] # Returns the ith array in the vector of arrays
-A[j,i] # Returns the jth component in the ith array
-A[j1,...,jN,i] # Returns the (j1,...,jN) component of the ith array
-```
-
-which presents itself as a column-major matrix with the columns being the arrays from the vector.
-The `AbstractArray` interface is implemented, giving access to `copy`, `push`, `append!`, etc. functions,
-which act appropriately. Points to note are:
-
-- The length is the number of vectors, or `length(A.u)` where `u` is the vector of arrays.
-- Iteration follows the linear index and goes over the vectors
-
-Additionally, the `convert(Array,VA::AbstractVectorOfArray)` function is provided, which transforms
-the `VectorOfArray` into a matrix/tensor. Also, `vecarr_to_vectors(VA::AbstractVectorOfArray)`
-returns a vector of the series for each component, that is, `A[i,:]` for each `i`.
-A plot recipe is provided, which plots the `A[i,:]` series.
-
-#### DiffEqArray
-
-Related to the `VectorOfArray` is the `DiffEqArray`
-
-```julia
-DiffEqArray(u::AbstractVector,t::AbstractVector)
-```
-
-This is a `VectorOfArray`, which stores `A.t` that matches `A.u`. This will plot
-`(A.t[i],A[i,:])`. The function `tuples(diffeq_arr)` returns tuples of `(t,u)`.
-
-To construct a DiffEqArray
-```julia
-t = 0.0:0.1:10.0
-f(t) = t - 1
-f2(t) = t^2
-vals = [[f(tval) f2(tval)] for tval in t]
-A = DiffEqArray(vals, t)
-A[1,:]  # all time periods for f(t)
-A.t
-```
-
-#### ArrayPartition
-
-```julia
-ArrayPartition(x::AbstractArray...)
-```
-
-An `ArrayPartition` `A` is an array, which is made up of different arrays `A.x`.
-These index like a single array, but each subarray may have a different type.
-However, broadcast is overloaded to loop in an efficient manner, meaning that
-`A .+= 2.+B` is type-stable in its computations, even if `A.x[i]` and `A.x[j]`
-do not match types. A full array interface is included for completeness, which
-allows this array type to be used in place of a standard array where
-such a type stable broadcast may be needed. One example is in heterogeneous
-differential equations for [DifferentialEquations.jl](https://github.com/JuliaDiffEq/DifferentialEquations.jl).
-
-An `ArrayPartition` acts like a single array. `A[i]` indexes through the first
-array, then the second, etc., all linearly. But `A.x` is where the arrays are stored.
-Thus, for:
-
-```julia
-using RecursiveArrayTools
-A = ArrayPartition(y,z)
-```
-
-we would have `A.x[1]==y` and `A.x[2]==z`. Broadcasting like `f.(A)` is efficient.
-
-### Functions
-
-```julia
-recursivecopy!(b::Array{T,N},a::Array{T,N})
-```
-
-A recursive `copy!` function. Acts like a `deepcopy!` on arrays of arrays, but
-like `copy!` on arrays of scalars.
-
-```julia
-convert(Array,vecvec)
-```
-
-Technically, just a Base fallback that works well. Takes in a vector of arrays,
-returns an array of dimension one greater than the original elements.
-Works on `AbstractVectorOfArray`. If the `vecvec` is ragged, i.e., not all of the
-elements are the same, then it uses the size of the first element to determine
-the conversion.
-
-```julia
-vecvecapply(f::Base.Callable,v)
-```
-
-Calls `f` on each element of a vecvec `v`.
-
-```julia
-copyat_or_push!{T}(a::AbstractVector{T},i::Int,x)
-```
-
-If `i<length(x)`, it's simply a `recursivecopy!` to the `i`th element. Otherwise, it will
-`push!` a `deepcopy`.
-
-```julia
-recursive_one(a)
-```
-
-Calls `one` on the bottom container to get the "true element one type".
-
-```julia
-mean{T<:AbstractArray}(vecvec::Vector{T})
-mean{T<:AbstractArray}(matarr::Matrix{T},region=0)
-```
-
-Generalized mean functions for vectors of arrays and a matrix of arrays.
+arrays of arrays.

docs/.gitignore

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

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"

docs/make.jl

@@ -0,0 +1,19 @@
+using Documenter, RecursiveArrayTools
+
+include("pages.jl")
+
+makedocs(
+    sitename="RecursiveArrayTools.jl",
+    authors="Chris Rackauckas",
+    modules=[RecursiveArrayTools],
+    clean=true,doctest=false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://recursivearraytools.sciml.ai/stable/"),
+    pages=pages
+)
+
+deploydocs(
+   repo = "github.com/SciML/RecursiveArrayTools.jl.git";
+   push_preview = true
+)

docs/pages.jl

@@ -0,0 +1,7 @@
+# Put in a separate page so it can be used by SciMLDocs.jl
+
+pages=[
+    "Home" => "index.md",
+    "array_types.md",
+    "recursive_array_functions.md"
+]

docs/src/array_types.md

@@ -0,0 +1,16 @@
+# Recursive Array Types
+
+The Recursive Array types are types which implement an `AbstractArray` interface so
+that recursive arrays can be handled with standard array functionality. For example,
+wrapped arrays will automatically do things like recurse broadcast, define optimized
+mapping and iteration functions, and more.
+
+## Abstract Types
+
+## Concrete Types
+
+```@docs
+VectorOfArray
+DiffEqArray
+ArrayPartition
+```

docs/src/index.md

@@ -0,0 +1,27 @@
+# RecursiveArrayTools.jl: Arrays of Arrays and Even Deeper
+
+RecursiveArrayTools.jl is a set of tools for dealing with recursive arrays like
+arrays of arrays. It contains type wrappers for making recursive arrays act more
+like normal arrays (for example, automating the recursion of broadcast, maps,
+iteration, and more), and utility functions which make it easier to work with
+recursive arrays.
+
+## Installation
+
+To install RecursiveArrayTools.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("RecursiveArrayTools")
+```
+
+## Contributing
+
+- Please refer to the
+  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+  for guidance on PRs, issues, and other matters relating to contributing to SciML.
+- There are a few community forums:
+    - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
+    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
+    - on the [Julia Discourse forums](https://discourse.julialang.org)
+    - see also [SciML Community page](https://sciml.ai/community/)

docs/src/recursive_array_functions.md

@@ -0,0 +1,13 @@
+# Recursive Array Functions
+
+These are functions designed for recursive arrays, like arrays of arrays,
+and do not require that the RecursiveArrayTools types are used.
+
+## Function List
+
+```@docs
+recursivecopy
+recursivecopy!
+vecvecapply
+copyat_or_push!
+```

src/array_partition.jl

@@ -1,3 +1,28 @@
+"""
+```julia
+ArrayPartition(x::AbstractArray...)
+```
+
+An `ArrayPartition` `A` is an array, which is made up of different arrays `A.x`.
+These index like a single array, but each subarray may have a different type.
+However, broadcast is overloaded to loop in an efficient manner, meaning that
+`A .+= 2.+B` is type-stable in its computations, even if `A.x[i]` and `A.x[j]`
+do not match types. A full array interface is included for completeness, which
+allows this array type to be used in place of a standard array where
+such a type stable broadcast may be needed. One example is in heterogeneous
+differential equations for [DifferentialEquations.jl](https://github.com/JuliaDiffEq/DifferentialEquations.jl).
+
+An `ArrayPartition` acts like a single array. `A[i]` indexes through the first
+array, then the second, etc., all linearly. But `A.x` is where the arrays are stored.
+Thus, for:
+
+```julia
+using RecursiveArrayTools
+A = ArrayPartition(y,z)
+```
+
+we would have `A.x[1]==y` and `A.x[2]==z`. Broadcasting like `f.(A)` is efficient.
+"""
 struct ArrayPartition{T,S<:Tuple} <: AbstractVector{T}
   x::S
 end