Add Documenter docs

Author: timholy

.travis.yml

@@ -15,3 +15,14 @@ notifications:
 after_success:
   # push coverage results to Codecov
   - julia -e 'using Pkg, OffsetArrays; cd(joinpath(dirname(pathof(OffsetArrays)), "..")); Pkg.add("Coverage"); using Coverage; Codecov.submit(Codecov.process_folder())'
+
+jobs:
+  include:
+    - stage: "Documentation"
+      julia: 1
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));
+                                               Pkg.instantiate()'
+        - julia --project=docs/ docs/make.jl
+      after_success: skip

Project.toml

@@ -1,6 +1,6 @@
 name = "OffsetArrays"
 uuid = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
-version = "1.0.0"
+version = "1.0.1"
 
 [compat]
 julia = "0.7, 1"

README.md

@@ -48,73 +48,6 @@ OA[-1, 0] = 1
 OA[1, 4] = 15
 ```
 
-OffsetArrays works for arbitrary dimensionality:
-
-```julia
-julia> using OffsetArrays
-
-julia> y = OffsetArray{Float64}(undef, -1:1, -7:7, -128:512, -5:5, -1:1, -3:3, -2:2, -1:1);
-
-julia> summary(y)
-"OffsetArrays.OffsetArray{Float64,8,Array{Float64,8}} with indices -1:1×-7:7×-128:512×-5:5×-1:1×-3:3×-2:2×-1:1"
-
-julia> y[-1,-7,-128,-5,-1,-3,-2,-1] = 14
-14
-
-julia> y[-1,-7,-128,-5,-1,-3,-2,-1] += 5
-19.0
-```
-
-## Example: Relativistic Notation
-Suppose we have a position vector `r = [:x, :y, :z]` which is naturally one-based, ie. `r[1] == :x`, `r[2] == :y`,  `r[3] == :z` and we also want to construct a relativistic position vector which includes time as the 0th component. This can be done with OffsetArrays like
-
-```julia
-julia> using OffsetArrays
-
-julia> r = [:x, :y, :z];
-
-julia> x = OffsetVector([:t, r...], 0:3)
-OffsetArray(::Array{Symbol,1}, 0:3) with eltype Symbol with indices 0:3:
- :t
- :x
- :y
- :z
-
-julia> x[0]
-:t
-
-julia> x[1:3]
-3-element Array{Symbol,1}:
- :x
- :y
- :z
-```
-
-## Example: Polynomials
-Suppose one wants to represent the Laurent polynomial
-```
-6/x + 5 - 2*x + 3*x^2 + x^3
-```
-in julia. The coefficients of this polynomial are a naturally `-1` based list, since the `n`th element of the list
-(counting from `-1`) `6, 5, -2, 3, 1` is the coefficient corresponding to the `n`th power of `x`. This Laurent polynomial can be evaluated at say `x = 2` as follows.
-```julia
-julia> using OffsetArrays
-
-julia> coeffs = OffsetVector([6, 5, -2, 3, 1], -1:3)
-OffsetArray(::Array{Int64,1}, -1:3) with eltype Int64 with indices -1:3:
-  6
-  5
- -2
-  3
-  1
-
-julia> polynomial(x, coeffs) = sum(coeffs[n]*x^n for n in eachindex(coeffs))
-polynomial (generic function with 1 method)
-
-julia> polynomial(2.0, coeffs)
-24.0
-```
-Notice our use of the `eachindex` function which does not assume that the given array starts at `1`.
 
 ## Notes on supporting OffsetArrays
 

appveyor.yml

@@ -1,7 +1,7 @@
 environment:
   matrix:
   - julia_version: 1.0
-  - julia_version: 1.3
+  - julia_version: 1
   - julia_version: nightly
 
 platform:

docs/.gitignore

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

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.24"

docs/make.jl

@@ -0,0 +1,14 @@
+using Documenter
+using OffsetArrays
+
+makedocs(
+    sitename = "OffsetArrays",
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
+    pages = ["index.md", "internals.md", "reference.md"],
+    modules = [OffsetArrays],
+    doctestfilters = [r"at \./.*", r"at /home.*", r"top-level scope.*", r"\[\d*\]\s*$"],   # for backtraces
+)
+
+deploydocs(
+    repo = "github.com:JuliaArrays/OffsetArrays.jl.git"
+)

docs/src/index.md

@@ -0,0 +1,121 @@
+# OffsetArrays.jl
+
+OffsetArrays provides Julia users with arrays that have arbitrary
+indices, similar to those found in some other programming languages
+like Fortran. Below is the basic usage found in the README, followed
+by a couple of short examples illustrating circumstances in which
+OffsetArrays can be useful. For a lengthier discussion, see
+[this blog post](https://julialang.org/blog/2017/04/offset-arrays/).
+
+## Usage
+
+You can construct such arrays as follows:
+
+```julia
+OA = OffsetArray(A, axis1, axis2, ...)
+```
+
+where you want `OA` to have axes `(axis1, axis2, ...)` and be indexed by values that
+fall within these axis ranges. Example:
+
+```julia
+using OffsetArrays
+A = Float64.(reshape(1:15, 3, 5))
+println("Here is A:")
+display(A)
+OA = OffsetArray(A, -1:1, 0:4)    # OA will have axes (-1:1, 0:4)
+println("Here is OA:")
+display(OA)
+@show OA[-1,0] OA[1,4]
+```
+
+gives the output
+
+```julia
+here is A:
+3×5 Array{Float64,2}:
+ 1.0  4.0  7.0  10.0  13.0
+ 2.0  5.0  8.0  11.0  14.0
+ 3.0  6.0  9.0  12.0  15.0
+here is OA:
+3×5 OffsetArray(::Array{Float64,2}, -1:1, 0:4) with eltype Float64 with indices -1:1×0:4:
+ 1.0  4.0  7.0  10.0  13.0
+ 2.0  5.0  8.0  11.0  14.0
+ 3.0  6.0  9.0  12.0  15.0
+OA[-1, 0] = 1.0
+OA[1, 4] = 15.0
+```
+
+OffsetArrays works for arbitrary dimensionality:
+
+```julia
+julia> using OffsetArrays
+
+julia> y = OffsetArray{Float64}(undef, -1:1, -7:7, -128:512, -5:5, -1:1, -3:3, -2:2, -1:1);
+
+julia> summary(y)
+"OffsetArrays.OffsetArray{Float64,8,Array{Float64,8}} with indices -1:1×-7:7×-128:512×-5:5×-1:1×-3:3×-2:2×-1:1"
+
+julia> y[-1,-7,-128,-5,-1,-3,-2,-1] = 14
+14
+
+julia> y[-1,-7,-128,-5,-1,-3,-2,-1] += 5
+19.0
+```
+
+You can use `OffsetArrays.no_offset_view(A)` if you want to return a view of the data in `A` but where indexing starts at 1.
+
+## Example: Relativistic Notation
+
+Suppose we have a position vector `r = [:x, :y, :z]` which is naturally one-based, ie. `r[1] == :x`, `r[2] == :y`,  `r[3] == :z` and we also want to construct a relativistic position vector which includes time as the 0th component. This can be done with OffsetArrays like
+
+```jldoctest
+julia> using OffsetArrays
+
+julia> r = [:x, :y, :z];
+
+julia> x = OffsetVector([:t, r...], 0:3)
+4-element OffsetArray(::Array{Symbol,1}, 0:3) with eltype Symbol with indices 0:3:
+ :t
+ :x
+ :y
+ :z
+
+julia> x[0]
+:t
+
+julia> x[1:3]
+3-element Array{Symbol,1}:
+ :x
+ :y
+ :z
+```
+
+## Example: Polynomials
+
+Suppose one wants to represent the Laurent polynomial
+```
+6/x + 5 - 2*x + 3*x^2 + x^3
+```
+in julia. The coefficients of this polynomial are a naturally `-1` based list, since the `n`th element of the list
+(counting from `-1`) `6, 5, -2, 3, 1` is the coefficient corresponding to the `n`th power of `x`. This Laurent polynomial can be evaluated at say `x = 2` as follows.
+
+```jldoctest
+julia> using OffsetArrays
+
+julia> coeffs = OffsetVector([6, 5, -2, 3, 1], -1:3)
+5-element OffsetArray(::Array{Int64,1}, -1:3) with eltype Int64 with indices -1:3:
+  6
+  5
+ -2
+  3
+  1
+
+julia> polynomial(x, coeffs) = sum(coeffs[n]*x^n for n in eachindex(coeffs))
+polynomial (generic function with 1 method)
+
+julia> polynomial(2.0, coeffs)
+24.0
+```
+
+Notice our use of the `eachindex` function which does not assume that the given array starts at `1`.

docs/src/internals.md

@@ -0,0 +1,108 @@
+# For developers
+
+Writing code that supports OffsetArrays is generally fairly straightforward.
+The majority of cases can be handled with these tips:
+
+- replace many uses of `size` with `axes`
+- replace `1:length(A)` with `eachindex(A)`, or if you need an integer index with `LinearIndices(A)`
+- replace explicit allocations like `Array{Int}(undef, size(B))` with `similar(Array{Int}, axes(B))`
+
+More information can be found in [Julia's developer documentation](https://docs.julialang.org/en/v1.0/devdocs/offset-arrays/).
+The most subtle issues tend to arise around the axes, and further detail specific to
+OffsetArrays.jl follows below.
+
+## Internals
+
+How does OffsetArrays work? The fundamental principle is very simple:
+an `OffsetArray` is just a wrapper around a "parent" array, together
+with an index offset:
+
+```jldoctest oa; setup=:(using OffsetArrays)
+julia> oa = OffsetArray([1 2; 3 4], 0:1, 5:6)
+2×2 OffsetArray(::Array{Int64,2}, 0:1, 5:6) with eltype Int64 with indices 0:1×5:6:
+ 1  2
+ 3  4
+
+julia> parent(oa)
+2×2 Array{Int64,2}:
+ 1  2
+ 3  4
+
+julia> oa.offsets
+(-1, 4)
+```
+
+So `parent(oa)` is the original array we constructed it with, and `oa.offsets` is a tuple,
+each entry encoding the index-shift to be applied along the corresponding axis.
+When you index `oa[i,j]`, it "translates" the `i,j` indexes back to the parent array's
+indexes and then returns the value in the parent.
+
+## The axes of OffsetArrays
+
+```jldoctest oa
+julia> axes(oa)
+(0:1, 5:6)
+```
+
+This looks straightforward, but if you dive deeper you'll notice some complexities:
+
+```jldoctest oa
+julia> ax = axes(oa, 2)
+5:6
+
+julia> typeof(ax)
+OffsetArrays.IdOffsetRange{Int64,Base.OneTo{Int64}}
+
+julia> ax[1]
+ERROR: BoundsError: attempt to access 2-element Base.OneTo{Int64} at index [-3]
+Stacktrace:
+ [1] throw_boundserror(::Base.OneTo{Int64}, ::Int64) at ./abstractarray.jl:538
+ [2] getindex at ./range.jl:625 [inlined]
+ [3] getindex(::OffsetArrays.IdOffsetRange{Int64,Base.OneTo{Int64}}, ::Int64) at /home/tim/.julia/dev/OffsetArrays/src/axes.jl:139
+ [4] top-level scope at none:0
+
+julia> ax[5]
+5
+```
+
+The axes are of type [`OffsetArrays.IdOffsetRange`](@ref).
+`IdOffsetRange`s are essentially OffsetArrays specialized for ranges, with the additional
+property that they tend to be their own axes:
+
+```jldoctest oa
+julia> ax
+5:6
+
+julia> axes(ax)
+(5:6,)
+
+julia> axes(ax[ax])
+(5:6,)
+```
+
+This example of indexing is [idempotent](https://en.wikipedia.org/wiki/Idempotence).
+This is a useful characteristic for ensuring the "fundamental axiom" of generalized indexing,
+that `a[rng][i] == a[rng[i]]`:
+
+```jldoctest; setup=:(using OffsetArrays)
+julia> oa2 = OffsetArray([5, 10, 15, 20], 0:3)
+4-element OffsetArray(::Array{Int64,1}, 0:3) with eltype Int64 with indices 0:3:
+  5
+ 10
+ 15
+ 20
+
+julia> ax2 = axes(oa2, 1)
+0:3
+
+julia> oa2[2]
+15
+
+julia> oa2[ax2][2]
+15
+
+julia> oa2[ax2[2]]
+15
+```
+
+`IdOffsetRange`s apply the offset both to the values and the indices of the range, and otherwise preserve the parent range.

docs/src/reference.md

@@ -0,0 +1,7 @@
+# Reference
+
+```@docs
+OffsetArray
+OffsetArrays.IdOffsetRange
+OffsetArrays.no_offset_view
+```