add some docs (#26)

closes #2

Author: simeonschaub

docs/Manifest.toml

@@ -74,10 +74,10 @@ uuid = "39de3d68-74b9-583c-8d2d-e117c070f3a9"
 version = "0.4.7"
 
 [[deps.AztecDiamonds]]
-deps = ["Adapt", "Colors", "ImageIO", "ImageShow", "KernelAbstractions", "OffsetArrays", "Transducers"]
+deps = ["Adapt", "Base64", "Colors", "ImageIO", "ImageShow", "KernelAbstractions", "OffsetArrays", "Transducers"]
 path = ".."
 uuid = "8762d9c5-fcab-4007-8fd1-c6de73397726"
-version = "0.2.3"
+version = "0.2.4"
 
     [deps.AztecDiamonds.extensions]
     MakieExtension = ["Makie", "GeometryBasics"]
@@ -358,9 +358,9 @@ version = "0.7.10"
     Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [[deps.InverseFunctions]]
-git-tree-sha1 = "2787db24f4e03daf859c6509ff87764e4182f7d1"
+git-tree-sha1 = "a779299d77cd080bf77b97535acecd73e1c5e5cb"
 uuid = "3587e190-3f89-42d0-90ee-14403ec27112"
-version = "0.1.16"
+version = "0.1.17"
 weakdeps = ["Dates", "Test"]
 
     [deps.InverseFunctions.extensions]

docs/make.jl

@@ -6,7 +6,7 @@ DocMeta.setdocmeta!(AztecDiamonds, :DocTestSetup, :(using AztecDiamonds); recurs
 makedocs(;
     modules = [AztecDiamonds],
     authors = "Simeon David Schaub <schaub@mit.edu> and contributors",
-    repo = "https://github.com/JuliaLabs/AztecDiamonds.jl/blob/{commit}{path}#{line}",
+    repo = Remotes.GitHub("JuliaLabs", "AztecDiamonds.jl"),
     sitename = "AztecDiamonds.jl",
     format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
@@ -25,4 +25,5 @@ makedocs(;
 deploydocs(;
     repo = "github.com/JuliaLabs/AztecDiamonds.jl",
     devbranch = "main",
+    push_preview = true,
 )

docs/src/index.md

@@ -6,6 +6,15 @@ CurrentModule = AztecDiamonds
 
 Documentation for [AztecDiamonds](https://github.com/JuliaLabs/AztecDiamonds.jl).
 
+For an example notebook using this package, see [here](https://julia.mit.edu/AztecDiamonds.jl/examples/stable/notebook.html).
+
+Here's a random diamond:
+
+```@example
+using AztecDiamonds
+show(stdout, MIME("text/plain"), diamond(10))
+```
+
 ```@index
 ```
 

src/AztecDiamonds.jl

@@ -9,11 +9,41 @@ export Tiling, diamond, ka_diamond, dr_path
 
 inds(N) = ((1 - N):N, (1 - N):N)
 
+"""
+    Tiling(N::Int[, x::OffsetMatrix{AztecDiamonds.Edge}]; sizehint::Int = N)
+
+Represents an order N diamond-shaped tiling. If `x` is not provided, it is initialized with `NONE`
+representing an empty tiling. The `sizehint` keyword argument may be used to preallocate a larger
+matrix for `x` fitting a tiling of order `sizehint` to avoid reallocations when the tiling grows.
+
+The indices of `x` represent the coordinates of the diamond-shaped tiling and run from 1-N to N
+(though `x` is allowed to be larger as long as it contains these indices).
+The edges it contains can either be `UP`, `RIGHT`, or `NONE`, where `UP` represents a vertical tile
+covering one more tile to the top, `RIGHT` represents a horizontal tile covering one more tile to
+the right. `NONE` means the edge is either already covered by another tile to the bottom or left or
+the tiling is not fully filled yet.
+
+```jldoctest
+julia> t = Tiling(1)
+1-order Tiling{Matrix{AztecDiamonds.Edge}}
+
+
+
+julia> t[0, 0] = t[1, 0] = AztecDiamonds.RIGHT;
+
+julia> t
+1-order Tiling{Matrix{AztecDiamonds.Edge}}
+🬇🬋🬋🬃
+🬇🬋🬋🬃
+```
+
+See [`diamond`](@ref) and [`ka_diamond`](@ref) for constructing a filled tiling.
+"""
 struct Tiling{M <: AbstractMatrix{Edge}}
     N::Int
     x::OffsetMatrix{Edge, M}
 end
-Tiling(N::Int; sizehint = N) = Tiling(N, fill(NONE, inds(sizehint)))
+Tiling(N::Int; sizehint::Int = N) = Tiling(N, fill(NONE, inds(sizehint)))
 
 in_diamond(N, i, j) = abs(2i - 1) + abs(2j - 1) ≤ 2N
 Base.checkbounds(::Type{Bool}, (; N)::Tiling, i, j) = in_diamond(N, i, j)
@@ -145,7 +175,32 @@ function diamond!(t, t′, N)
     return t
 end
 
-function diamond(N)
+"""
+    diamond(N::Int) -> Tiling{Matrix{AztecDiamonds.Edge}}
+
+Generates a uniformally random order N diamond tiling.
+
+```jldoctest
+julia> using Random; Random.seed!(1);
+
+julia> diamond(4)
+4-order Tiling{Matrix{AztecDiamonds.Edge}}
+      🬇🬋🬋🬃
+    🬇🬋🬋🬃🬇🬋🬋🬃
+  🬦🬓🬦🬓🬦🬓🬦🬓🬇🬋🬋🬃
+🬦🬓🬉🬄🬉🬄🬉🬄🬉🬄🬇🬋🬋🬃🬦🬓
+🬉🬄🬦🬓🬦🬓🬇🬋🬋🬃🬦🬓🬦🬓🬉🬄
+  🬉🬄🬉🬄🬇🬋🬋🬃🬉🬄🬉🬄
+    🬇🬋🬋🬃🬇🬋🬋🬃
+      🬇🬋🬋🬃
+```
+
+See [`ka_diamond`](@ref) for a version that can take advantage of GPU acceleration.
+`ka_diamond(N, Array)` may also be faster for large N.
+
+Ref [`Tiling`](@ref)
+"""
+function diamond(N::Int)
     t, t′ = Tiling(0; sizehint = N), Tiling(0; sizehint = N)
     return diamond!(t, t′, N)
 end

src/ka.jl

@@ -113,7 +113,15 @@ function ka_diamond!(t, t′, N; backend)
     return t
 end
 
-function ka_diamond(N, ArrayT)
+"""
+    ka_diamond(N::Int, ArrayT::Type{<:AbstractArray}) -> Tiling{ArrayT{Edge}}
+
+Generate a uniformly random diamond tiling just like [`diamond`](@ref), but using `KernelAbstractions.jl`
+to be able to take advantage of (GPU) parallelism. `ArrayT` can either be `Array` or any GPU array type.
+
+Ref [`Tiling`](@ref)
+"""
+function ka_diamond(N::Int, ArrayT::Type{<:AbstractArray})
     mem = ntuple(_ -> fill!(ArrayT{Edge}(undef, 2N, 2N), NONE), 2)
     t, t′ = map(x -> Tiling(0, OffsetMatrix(x, inds(N))), mem)
     return ka_diamond!(t, t′, N; backend = KernelAbstractions.get_backend(mem[1]))

src/show.jl

@@ -70,7 +70,7 @@ function Base.show(io::IO, ::MIME"text/plain", t::Tiling)
         elseif get(t, (i, j - 1), NONE) == RIGHT
             color = !isdotted ? :yellow : :blue
             printstyled(io, "🬋🬃"; color)
-        else
+        elseif j < 0 || in_diamond(N, i, j) # don't produce trailing spaces
             print(io, "  ")
         end
     end

test/show.jl

@@ -19,7 +19,7 @@ end
     N = 20
     D = diamond(N)
     r = repr(MIME("text/plain"), D)
-    @test length(r) > 2(2N)^2
+    @test length(r) == 2537
     r_color = repr(MIME("text/plain"), D; context = :color => true)
     @test length(r_color) == length(r) + 10length(AztecDiamonds.faces(D))
 
@@ -46,17 +46,18 @@ end
     t[2, -1] = RIGHT
     t[2, 0] = RIGHT
 
+    # TODO: should
     expected = replace(
         """
         4-order $Tiling{Matrix{AztecDiamonds.Edge}}
-              🬦🬓        \\
-              UU        \\
-              🬉🬄        \\
+              🬦🬓  \\
+              UU    \\
+              🬉🬄      \\
         🬇🬋UR  🬦🬓🬦🬓      \\
           🬉🬄🬇🬋NRRU🬋🬃    \\
-            🬇🬋RR🬋🬃      \\
-                        \\
-                        """,
+            🬇🬋RR🬋🬃    \\
+                    \\
+                  """,
         "\\" => ""
     )
     @test repr(MIME("text/plain"), t) == expected