Merge pull request #145 from JuliaArrays/jc/docs

update and add more docs

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 'master'
+      - 'release-'
+    tags: '*'
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        julia-version: [1]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.julia-version }}
+      - name: Cache artifacts
+        uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts 
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - 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 }}
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -1 +1,2 @@
 /Manifest.toml
+/docs/Manifest.toml

.travis.yml

@@ -15,14 +15,3 @@ 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

README.md

@@ -23,30 +23,24 @@ fall within these axis ranges. Example:
 
 ```julia
 using OffsetArrays
-A = 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]
-```
-
-which prints out
-
-```
-here is A:
-3×5 reshape(::UnitRange{Int64}, 3, 5) with eltype Int64:
- 1  4  7  10  13
- 2  5  8  11  14
- 3  6  9  12  15
-here is OA:
-OffsetArray(reshape(::UnitRange{Int64}, 3, 5), -1:1, 0:4) with eltype Int64 with indices -1:1×0:4:
- 1  4  7  10  13
- 2  5  8  11  14
- 3  6  9  12  15
-OA[-1, 0] = 1
-OA[1, 4] = 15
+julia> A = Float64.(reshape(1:15, 3, 5))
+3×5 Matrix{Float64}:
+ 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
+
+julia> OA = OffsetArray(A, -1:1, 0:4) # OA will have axes (-1:1, 0:4)
+3×5 OffsetArray(::Matrix{Float64}, -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
+
+julia> OA = OffsetArray(A, CartesianIndex(-1, 0):CartesianIndex(1, 4))
+3×5 OffsetArray(::Matrix{Float64}, -1:1, 0:4) with eltype Float64 with indices -1:1×0:4:
+[...]
+
+julia> OA[-1,0], OA[1,4]
+(1.0, 15.0)
 ```
 
 [pkgeval-img]: https://juliaci.github.io/NanosoldierReports/pkgeval_badges/O/OffsetArrays.svg

docs/Project.toml

@@ -1,5 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 
 [compat]
-Documenter = "0.24"
+Documenter = "0.25"

docs/make.jl

@@ -1,4 +1,4 @@
-using Documenter
+using Documenter, JSON
 using OffsetArrays
 
 makedocs(
@@ -9,6 +9,17 @@ makedocs(
     doctestfilters = [r"at \./.*", r"at /home.*", r"top-level scope.*", r"\[\d*\]\s*$"],   # for backtraces
 )
 
+# a workdaround to github action that only push preview when PR has "push_preview" labels
+# issue: https://github.com/JuliaDocs/Documenter.jl/issues/1225
+function should_push_preview(event_path = get(ENV, "GITHUB_EVENT_PATH", nothing))
+    event_path === nothing && return false
+    event = JSON.parsefile(event_path)
+    haskey(event, "pull_request") || return false
+    labels = [x["name"] for x in event["pull_request"]["labels"]]
+    return "push_preview" in labels
+ end
+
 deploydocs(
-    repo = "github.com:JuliaArrays/OffsetArrays.jl.git"
+    repo = "github.com:JuliaArrays/OffsetArrays.jl.git",
+    push_preview = should_push_preview()
 )

docs/src/index.md

@@ -16,66 +16,54 @@ 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:
+fall within these axis ranges.
 
-```julia
+```@repl index
 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]
+
+OA = OffsetArray(A, -1:1, 0:4) # OA will have axes (-1:1, 0:4)
+
+OA = OffsetArray(A, CartesianIndex(-1, 0):CartesianIndex(1, 4))
+
+OA[-1,0], OA[1,4]
 ```
 
-gives the output
+You could also pass integers as offsets, where `0` means no offsets are applied:
 
-```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
+```@repl index
+OA = OffsetArray(A, -2, -1)
 ```
 
-OffsetArrays works for arbitrary dimensionality:
+When you create a new `OffsetArray` on the top of another `OffsetArray`, the offsets are
+accumulated:
 
-```julia
-julia> using OffsetArrays
+```@repl index
+OOA = OffsetArray(OA, 2, 1)
+```
 
-julia> y = OffsetArray{Float64}(undef, -1:1, -7:7, -128:512, -5:5, -1:1, -3:3, -2:2, -1:1);
+For the special cases that you want to compensate the offset back to the ordinary 1-based array, you
+can use [`OffsetArrays.no_offset_view(A)`](@ref). Furthermore, you could use
+`Base.require_one_based_indexing` if you want to ensure the array does not have offsets.
 
-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"
+```@repl index
+OffsetArrays.no_offset_view(OA)
 
-julia> y[-1,-7,-128,-5,-1,-3,-2,-1] = 14
-14
+Base.require_one_based_indexing(ans)
 
-julia> y[-1,-7,-128,-5,-1,-3,-2,-1] += 5
-19.0
+Base.require_one_based_indexing(OA)
 ```
 
-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
-
+```jldoctest; setup = :(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:
+4-element OffsetArray(::Vector{Symbol}, 0:3) with eltype Symbol with indices 0:3:
  :t
  :x
  :y
@@ -85,7 +73,7 @@ julia> x[0]
 :t
 
 julia> x[1:3]
-3-element Array{Symbol,1}:
+3-element Vector{Symbol}:
  :x
  :y
  :z
@@ -94,17 +82,17 @@ julia> x[1:3]
 ## Example: Polynomials
 
 Suppose one wants to represent the Laurent polynomial
-```
+
+```math
 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
+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; setup = :(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:
+5-element OffsetArray(::Vector{Int64}, -1:3) with eltype Int64 with indices -1:3:
   6
   5
  -2