Merge pull request #298 from jw3126/docs

Use Documenter.jl for documentation (# 70)

Author: c42f

.travis.yml

@@ -9,8 +9,9 @@ julia:
 notifications:
   email: false
 branches:
-  only: # Only kick off CI for master and potential merges to master from within PRs
+  only:
     - master
+    - /^v[0-9]+\.[0-9]+\.[0-9]+$/ # version tags for Documenter.jl, see # 298
 matrix:
   allow_failures:
     - julia: nightly
@@ -23,3 +24,5 @@ after_success:
   - if [ $TRAVIS_JULIA_VERSION = "0.6" ] && [ $TRAVIS_OS_NAME = "linux" ]; then
       julia -e 'cd(Pkg.dir("StaticArrays")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder()); Codecov.submit(Codecov.process_folder())';
     fi
+  - julia -e 'Pkg.add("Documenter")'
+  - julia -e 'cd(Pkg.dir("StaticArrays")); include(joinpath("docs", "make.jl"))'

README.md

@@ -8,6 +8,8 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/xabgh1yhsjxlp30d?svg=true)](https://ci.appveyor.com/project/JuliaArrays/staticarrays-jl)
 [![Coverage Status](https://coveralls.io/repos/github/JuliaArrays/StaticArrays.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaArrays/StaticArrays.jl?branch=master)
 [![codecov.io](http://codecov.io/github/JuliaArrays/StaticArrays.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaArrays/StaticArrays.jl?branch=master)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaArrays.github.io/StaticArrays.jl/latest)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaArrays.github.io/StaticArrays.jl/stable)
 
 **StaticArrays** provides a framework for implementing statically sized arrays
 in Julia (≥ 0.5), using the abstract type `StaticArray{Size,T,N} <: AbstractArray{T,N}`.
@@ -22,6 +24,7 @@ Mutable versions `MVector`, `MMatrix` and `MArray` are also exported, as well
 as `SizedArray` for annotating standard `Array`s with static size information.
 Further, the abstract `FieldVector` can be used to make fast `StaticVector`s
 out of any uniform Julia "struct".
+Full documentation can be found [here](https://JuliaArrays.github.io/StaticArrays.jl/stable/).
 
 ## Speed
 
@@ -141,309 +144,6 @@ precise dimensions of the input. In combination with intelligent fallbacks to
 the methods in Base, we seek to provide a comprehensive support for statically
 sized arrays, large or small, that hopefully "just works".
 
-## API Details
-
-### The `Size` trait
-
-The size of a statically sized array is a static parameter associated with the
-type of the array. The `Size` trait is provided as an abstract representation of
-the dimensions of a static array. An array `sa::SA` of size `(dims...)` is
-associated with `Size{(dims...)}()`. The following are equivalent (`@pure`)
-constructors:
-```julia
-Size{(dims...)}()
-Size(dims...)
-Size(sa::StaticArray)
-Size(SA) # SA <: StaticArray
-```
-This is extremely useful for (a) performing dispatch depending on the size of an
-array, and (b) passing array dimensions that the compiler can reason about.
-
-An example of size-based dispatch for the determinant of a matrix would be:
-```julia
-det(x::StaticMatrix) = _det(Size(x), x)
-_det(::Size{(1,1)}, x::StaticMatrix) = x[1,1]
-_det(::Size{(2,2)}, x::StaticMatrix) = x[1,1]*x[2,2] - x[1,2]*x[2,1]
-# and other definitions as necessary
-```
-
-Examples of using `Size` as a compile-time constant include
-```julia
-reshape(svector, Size(2,2))  # Convert SVector{4} to SMatrix{2,2}
-Size(3,3)(rand(3,3))         # Construct a random 3×3 SizedArray (see below)
-```
-
-### Indexing
-
-Statically sized indexing can be realized by indexing each dimension by a
-scalar, a `StaticVector` or `:`. Indexing in this way will result a statically
-sized array (even if the input was dynamically sized, in the case of
-`StaticVector` indices) of the closest type (as defined by `similar_type`).
-
-Conversely, indexing a statically sized array with a dynamically sized index
-(such as a `Vector{Integer}` or `UnitRange{Integer}`) will result in a standard
-(dynamically sized) `Array`.
-
-### `similar_type()`
-
-Since immutable arrays need to be constructed "all-at-once", we need a way of
-obtaining an appropriate constructor if the element type or dimensions of the
-output array differs from the input. To this end, `similar_type` is introduced,
-behaving just like `similar`, except that it returns a type. Relevant methods
-are:
-
-```julia
-similar_type{A <: StaticArray}(::Type{A}) # defaults to A
-similar_type{A <: StaticArray, ElType}(::Type{A}, ::Type{ElType}) # Change element type
-similar_type{A <: AbstractArray}(::Type{A}, size::Size) # Change size
-similar_type{A <: AbstractArray, ElType}(::Type{A}, ::Type{ElType}, size::Size) # Change both
-```
-
-These setting will affect everything, from indexing, to matrix multiplication
-and `broadcast`. Users wanting introduce a new array type should *only* overload
-the last method in the above.
-
-Use of `similar` will fall back to a mutable container, such as a `MVector`
-(see below), and it requires use of the `Size` trait if you wish to set a new
-static size (or else a dynamically sized `Array` will be generated when
-specifying the size as plain integers).
-
-### `SVector`
-
-The simplest static array is the type `SVector{N,T}`, which provides an
-immutable vector of fixed length `N` and type `T`.
-
-`SVector` defines a series of convenience constructors, so you can just type
-e.g. `SVector(1,2,3)`. Alternatively there is an intelligent `@SVector` macro
-where you can use native Julia array literals syntax, comprehensions, and the
-`zeros()`, `ones()`, `fill()`, `rand()` and `randn()` functions, such as `@SVector [1,2,3]`,
-`@SVector Float64[1,2,3]`, `@SVector [f(i) for i = 1:10]`, `@SVector zeros(3)`,
-`@SVector randn(Float32, 4)`, etc (Note: the range of a comprehension is evaluated at global scope by the
-macro, and must be made of combinations of literal values, functions, or global
-variables, but is not limited to just simple ranges. Extending this to
-(hopefully statically known by type-inference) local-scope variables is hoped
-for the future. The `zeros()`, `ones()`, `fill()`, `rand()` and `randn()` functions do not have this
-limitation.)
-
-### `SMatrix`
-
-Statically sized `N×M` matrices are provided by `SMatrix{N,M,T,L}`.
-
-Here `L` is the `length` of the matrix, such that `N × M = L`. However,
-convenience constructors are provided, so that `L`, `T` and even `M` are
-unnecessary. At minimum, you can type `SMatrix{2}(1,2,3,4)` to create a 2×2
-matrix (the total number of elements must divide evenly into `N`). A
-convenience macro `@SMatrix [1 2; 3 4]` is provided (which also accepts
-comprehensions and the `zeros()`, `ones()`, `fill()`, `rand()`, `randn()` and `eye()`
-functions).
-
-### `SArray`
-
-A container with arbitrarily many dimensions is defined as
-`struct SArray{Size,T,N,L} <: StaticArray{Size,T,N}`, where
-`Size = Tuple{S1, S2, ...}` is a tuple of `Int`s. You can easily construct one with
-the `@SArray` macro, supporting all the features of `@SVector` and `@SMatrix`
-(but with arbitrary dimension).
-
-The main reason `SVector` and `SMatrix` are defined is to make it easier to
-define the types without the extra tuple characters (compare `SVector{3}` to
-`SArray{Tuple{3}}`).
-
-### `Scalar`
-
-Sometimes you want to broadcast an operation, but not over one of your inputs.
-A classic example is attempting to displace a collection of vectors by the
-same vector. We can now do this with the `Scalar` type:
-
-```julia
-[[1,2,3], [4,5,6]] .+ Scalar([1,0,-1]) # [[2,2,2], [5,5,5]]
-```
-
-`Scalar` is simply an implementation of an immutable, 0-dimensional `StaticArray`.
-
-### Mutable arrays: `MVector`, `MMatrix` and `MArray`
-
-These statically sized arrays are identical to the above, but are defined as
-`mutable struct`s, instead of immutable `struct`s. Because they are mutable, they
-allow `setindex!` to be defined (achieved through pointer manipulation, into a
-tuple).
-
-As a consequence of Julia's internal implementation, these mutable containers
-live on the heap, not the stack. Their memory must be allocated and tracked by
-the garbage collector. Nevertheless, there is opportunity for speed
-improvements relative to `Base.Array` because (a) there may be one less
-pointer indirection, (b) their (typically small) static size allows for
-additional loop unrolling and inlining, and consequentially (c) their mutating
-methods like `map!` are extremely fast. Benchmarking shows that operations such
-as addition and matrix multiplication are faster for `MMatrix` than `Matrix`,
-at least for sizes up to 14 × 14, though keep in mind that optimal speed will
-be obtained by using mutating functions (like `map!` or `A_mul_B!`) where
-possible, rather than reallocating new memory.
-
-Mutable static arrays also happen to be very useful containers that can be
-constructed on the heap (with the ability to use `setindex!`, etc), and later
-copied as e.g. an immutable `SVector` to the stack for use, or into e.g. an
-`Array{SVector}` for storage.
-
-Convenience macros `@MVector`, `@MMatrix` and `@MArray` are provided.
-
-### `SizedArray`: a decorate size wrapper for `Array`
-
-Another convenient mutable type is the `SizedArray`, which is just a wrapper-type
-about a standard Julia `Array` which declares its knwon size. For example, if
-we knew that `a` was a 2×2 `Matrix`, then we can type `sa = SizedArray{Tuple{2,2}}(a)`
-to construct a new object which knows the type (the size will be verified
-automatically). A more convenient syntax for obtaining a `SizedArray` is by calling
-a `Size` object, e.g. `sa = Size(2,2)(a)`.
-
-Then, methods on `sa` will use the specialized code provided by the *StaticArrays*
-pacakge, which in many cases will be much, much faster. For example, calling
-`eig(sa)` will be signficantly faster than `eig(a)` since it will perform a
-specialized 2×2 matrix diagonalization rather than a general algorithm provided
-by Julia and *LAPACK*.
-
-In some cases it will make more sense to use a `SizedArray`, and in other cases
-an `MArray` might be preferable.
-
-### `FieldVector`
-
-Sometimes it might be useful to imbue your own types, having multiple fields,
-with vector-like properties. *StaticArrays* can take care of this for you by
-allowing you to inherit from `FieldVector{N, T}`. For example, consider:
-
-```julia
-struct Point3D <: FieldVector{3, Float64}
-    x::Float64
-    y::Float64
-    z::Float64
-end
-```
-
-With this type, users can easily access fields to `p = Point3D(x,y,z)` using
-`p.x`, `p.y` or `p.z`, or alternatively via `p[1]`, `p[2]`, or `p[3]`. You may
-even permute the coordinates with `p[SVector(3,2,1)]`). Furthermore, `Point3D`
-is a complete `AbstractVector` implementation where you can add, subtract or
-scale vectors, multiply them by matrices, etc.
-
-It is also worth noting that `FieldVector`s may be mutable or immutable, and
-that `setindex!` is defined for use on mutable types. For immutable containers,
-you may want to define a method for `similar_type` so that operations leave the
-type constant (otherwise they may fall back to `SVector`). For mutable
-containers, you may want to define a default constructor (no inputs) and an
-appropriate method for `similar`,
-
-### Implementing your own types
-
-You can easily create your own `StaticArray` type, by defining linear
-`getindex` (and optionally `setindex!` for mutable types - see
-`setindex(::MArray, val, i)` in *MArray.jl* for an example of how to
-achieve this through pointer manipulation). Your type should define a constructor
-that takes a tuple of the data (and mutable containers may want to define a
-default constructor).
-
-Other useful functions to overload may be `similar_type` (and `similar` for
-mutable containers).
-
-### Conversions from `Array`
-
-In order to convert from a dynamically sized `AbstractArray` to one of the
-statically sized array types, you must specify the size explicitly.  For
-example,
-
-```julia
-v = [1,2]
-
-m = [1 2;
-     3 4]
-
-# ... a lot of intervening code
-
-sv = SVector{2}(v)
-sm = SMatrix{2,2}(m)
-sa = SArray{(2,2)}(m)
-
-sized_v = Size(2)(v)     # SizedArray{(2,)}(v)
-sized_m = Size(2,2)(m)   # SizedArray{(2,2)}(m)
-```
-
-We have avoided adding `SVector(v::AbstractVector)` as a valid constructor to
-help users avoid the type instability (and potential performance disaster, if
-used without care) of this innocuous looking expression. However, the simplest
-way to deal with an `Array` is to create a `SizedArray` by calling a `Size`
-instance, e.g. `Size(2)(v)`.
-
-### Arrays of static arrays
-
-Storing a large number of static arrays is convenient as an array of static
-arrays. For example, a collection of positions (3D coordinates - `SVector{3,Float64}`)
-could be represented as a `Vector{SVector{3,Float64}}`.
-
-Another common way of storing the same data is as a 3×`N` `Matrix{Float64}`.
-Rather conveniently, such types have *exactly* the same binary layout in memory,
-and therefore we can use `reinterpret` to convert between the two formats
-```julia
-function svectors(x::Matrix{Float64})
-    @assert size(x,1) == 3
-    reinterpret(SVector{3,Float64}, x, (size(x,2),))
-end
-```
-Such a conversion does not copy the data, rather it refers to the *same* memory
-referenced by two different Julia `Array`s. Arguably, a `Vector` of `SVector`s
-is preferable to a `Matrix` because (a) it provides a better abstraction of the
-objects contained in the array and (b) it allows the fast *StaticArrays* methods
-to act on elements.
-
-### Working with mutable and immutable arrays
-
-Generally, it is performant to rebind an *immutable* array, such as
-```julia
-function average_position(positions::Vector{SVector{3,Float64}})
-    x = zeros(SVector{3,Float64})
-    for pos ∈ positions
-        x = x + pos
-    end
-    return x / length(positions)
-end
-```
-so long as the `Type` of the rebound variable (`x`, above) does not change.
-
-On the other hand, the above code for mutable containers like `Array`, `MArray`
-or `SizedArray` is *not* very efficient. Mutable containers in Julia 0.5 must
-be *allocated* and later *garbage collected*, and for small, fixed-size arrays
-this can be a leading contribution to the cost. In the above code, a new array
-will be instantiated and allocated on each iteration of the loop. In order to
-avoid unnecessary allocations, it is best to allocate an array only once and
-apply mutating functions to it:
-```julia
-function average_position(positions::Vector{SVector{3,Float64}})
-    x = zeros(MVector{3,Float64})
-    for pos ∈ positions
-        # Take advantage of Julia 0.5 broadcast fusion
-        x .= (+).(x, pos) # same as broadcast!(+, x, x, positions[i])
-    end
-    x .= (/).(x, length(positions))
-    return x
-end
-```
-Keep in mind that Julia 0.5 does not fuse calls to `.+`, etc (or `.+=` etc),
-however the `.=` and `(+).()` syntaxes are fused into a single, efficient call
-to `broadcast!`. The simpler syntax `x .+= pos` is expected to be non-allocating
-(and therefore faster) in Julia 0.6.
-
-The functions `setindex`, `push`, `pop`, `shift`, `unshift`, `insert` and `deleteat`
-are provided for performing certain specific operations on static arrays, in
-analogy with the standard functions `setindex!`, `push!`, `pop!`, etc. (Note that
-if the size of the static array changes, the type of the output will differ from
-the input.)
-
-### SIMD optimizations
-
-It seems Julia and LLVM are smart enough to use processor vectorization
-extensions like SSE and AVX - however they are currently partially disabled by
-default. Run Julia with `julia -O` or `julia -O3` to enable these optimizations,
-and many of your (immutable) `StaticArray` methods *should* become significantly
-faster!
-
 ## Relationship to *FixedSizeArrays* and *ImmutableArrays*
 
 Several existing packages for statically sized arrays have been developed for

docs/.gitignore

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

docs/make.jl

@@ -0,0 +1,16 @@
+using Documenter, StaticArrays
+
+makedocs(
+         format = :html,
+         modules = [StaticArrays],
+         sitename = "StaticArrays.jl",
+         pages = [
+            "Home" => "index.md",
+            "API" => "pages/api.md",
+            "Quick Start" => "pages/quickstart.md",
+            ],
+        )
+
+deploydocs(
+    repo = "github.com/JuliaArrays/StaticArrays.jl",
+)

docs/src/index.md

@@ -0,0 +1,16 @@
+# Static Arrays
+*Statically sized arrays for Julia*
+
+**StaticArrays** provides a framework for implementing statically sized arrays
+in Julia (≥ 0.5), using the abstract type `StaticArray{Size,T,N} <: AbstractArray{T,N}`.
+Subtypes of [`StaticArray`](@ref) will provide fast implementations of common array and
+linear algebra operations. Note that here "statically sized" means that the
+size can be determined from the *type*, and "static" does **not** necessarily
+imply `immutable`.
+
+The package also provides some concrete static array types: [`SVector`](@ref), [`SMatrix`](@ref)
+and [`SArray`](@ref), which may be used as-is (or else embedded in your own type).
+Mutable versions [`MVector`](@ref), [`MMatrix`](@ref) and [`MArray`](@ref) are also exported, as well
+as [`SizedArray`](@ref) for annotating standard `Array`s with static size information.
+Further, the abstract [`FieldVector`](@ref) can be used to make fast static vectors
+out of any uniform Julia "struct".