Skip to content

Commit 3b5a1a2

Browse files
oschulzoschulz
committed
Use Documenter.jl for documentation
1 parent 58c2d74 commit 3b5a1a2

File tree

11 files changed

+241
-150
lines changed

11 files changed

+241
-150
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.DS_Store
12
*.jl.cov
23
*.jl.*.cov
34
*.jl.mem
5+
Manifest.toml

‎.travis.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,13 @@ after_success:
2626
- julia -e 'import Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(Codecov.process_folder())'
2727
# push coverage results to Coveralls
2828
- julia -e 'import Pkg; Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'
29+
30+
jobs:
31+
include:
32+
- stage: "Documentation"
33+
julia: 1.0
34+
os: linux
35+
script:
36+
- julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
37+
- julia --project=docs/ docs/make.jl
38+
after_success: skip

‎README.md

Lines changed: 9 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,19 @@
11
# ArraysOfArrays.jl
22

3-
[![Build Status](https://travis-ci.com/oschulz/ArraysOfArrays.jl.svg?branch=master)](https://travis-ci.com/oschulz/ArraysOfArrays.jl)
4-
[![Build Status](https://ci.appveyor.com/api/projects/status/github/oschulz/ArraysOfArrays.jl?branch=master&svg=true)](https://ci.appveyor.com/project/oschulz/ArraysOfArrays-jl)
3+
[![Documentation for stable version](https://img.shields.io/badge/docs-stable-blue.svg)](https://oschulz.github.io/ArraysOfArrays.jl/stable)
4+
[![Documentation for development version](https://img.shields.io/badge/docs-dev-blue.svg)](https://oschulz.github.io/ArraysOfArrays.jl/dev)
5+
[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](LICENSE.md)
6+
[![Travis Build Status](https://travis-ci.com/oschulz/ArraysOfArrays.jl.svg?branch=master)](https://travis-ci.com/oschulz/ArraysOfArrays.jl)
7+
[![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/github/oschulz/ArraysOfArrays.jl?branch=master&svg=true)](https://ci.appveyor.com/project/oschulz/ArraysOfArrays-jl)
58
[![Codecov](https://codecov.io/gh/oschulz/ArraysOfArrays.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/oschulz/ArraysOfArrays.jl)
69

710

811
A Julia package for efficient storage and handling of nested arrays.
912

1013
ArraysOfArrays provides two different types of nested arrays: `ArrayOfSimilarArrays` and `VectorOfArrays`.
14+
An `ArrayOfSimilarArrays` offers a duality of view between representing the same data as both a flat multi-dimensional array and as an array of equally-sized arrays. A `VectorOfArrays` represents a vector of arrays of equal dimensionality but different size. Internally, both types store their data in flat arrays that are accessible to the user `flatview()`.
1115

16+
## Documentation
1217

13-
## ArrayOfSimilarArrays
14-
15-
An `ArrayOfSimilarArrays` offers duality of viewing the same data as both a flat multi-dimensional array and as an array of equally-sized arrays:
16-
17-
```julia
18-
A_flat = rand(2,3,4,5,6)
19-
A_nested = nestedview(A_flat, 2)
20-
```
21-
22-
creates a view of `A_flat` as an array of arrays:
23-
24-
```julia
25-
A_nested isa AbstractArray{<:AbstractArray{T,2},3} where T
26-
```
27-
28-
`A_flat` is always available via `flatview`. `A_flat` and `A_nested` are backed by the same data, no data is copied:
29-
30-
```julia
31-
flatview(A_nested) === A_flat
32-
```
33-
34-
Calling `getindex` on `A_nested` returns a view into `A_flat`:
35-
36-
```julia
37-
fill!(A_nested[2, 4, 3], 4.2)
38-
all(x -> x == 4.2, A_flat[:, :, 2, 4, 3])
39-
```
40-
41-
### Type aliases
42-
43-
The following type aliases are defined:
44-
45-
* `VectorOfSimilarArrays{T,M} = AbstractArrayOfSimilarArrays{T,M,1}`
46-
* `ArrayOfSimilarVectors{T,N} = AbstractArrayOfSimilarArrays{T,1,N}`
47-
* `VectorOfSimilarVectors{T} = AbstractArrayOfSimilarArrays{T,1,1}`
48-
49-
For each of the types there is also an abstract type (`AbstractArrayOfSimilarArrays`, etc.).
50-
51-
If a `VectorOfSimilarArrays` is backed by an `ElasticArrays.ElasticArray`, additional element arrays can be pushed into it and `resize!` is available too:
52-
53-
### Appending data and resizing
54-
55-
```julia
56-
using ElasticArrays
57-
58-
A_nested = nestedview(ElasticArray{Float64}(undef, 2, 3, 0), 2)
59-
60-
for i in 1:4
61-
push!(A_nested, rand(2, 3))
62-
end
63-
size(flatview(A_nested)) == (2, 3, 4)
64-
65-
resize!(A_nested, 6)
66-
size(flatview(A_nested)) == (2, 3, 6)
67-
```
68-
69-
There is a full duality between the nested and the flat view of the data. `A_flat` may be resized freely without breaking the inner consistency of `A_nested`: Changes in the shape of one will result in changes in the shape of the other.
70-
71-
### Statistics functions
72-
73-
`AbstractVectorOfSimilarArrays` supports the functions `sum`, `mean` and `var`, `AbstractVectorOfSimilarVectors` additionally support `cov` and `cor`.
74-
75-
Methods for these function are defined both without and with weights (via `StatsBase.AbstractWeights`). Because of this, `ArraysOfArrays` currently requires `StatsBase`. It's possible that this requirement can be dropped in the future, though (see
76-
[Julia issue #29974](https://github.com/JuliaLang/julia/issues/29974)).
77-
78-
## VectorOfArrays
79-
80-
A `VectorOfArrays` represents a vector of arrays of equal dimensionality but different size. It is a nested interpretation of the concept of a "ragged array".
81-
82-
```julia
83-
VA = VectorOfArrays{Float64, 2}()
84-
85-
push!(VA, rand(2, 3))
86-
push!(VA, rand(4, 2))
87-
88-
size(VA[1]) == (2,3)
89-
size(VA[2]) == (4,2)
90-
```
91-
92-
Internally, all data is stored efficiently in a single, flat and memory-contiguous vector, accessible via `flatview`:
93-
94-
```julia
95-
VA_flat = flatview(VA)
96-
VA_flat isa Vector{Float64}
97-
```
98-
99-
Calling `getindex` on `A_nested` returns a view into `A_flat`:
100-
101-
```julia
102-
VA_flat = flatview(VA)
103-
view(VA_flat, 7:14) == vec(VA[2])
104-
105-
fill!(view(VA_flat, 7:14), 2.4)
106-
all(x -> x == 2.4, VA[2])
107-
108-
fill!(view(VA_flat, 7:14), 4.2)
109-
all(x -> x == 4.2, VA[2])
110-
```
111-
112-
### Type aliases
113-
The following type aliases are defined:
114-
115-
* `VectorOfVectors{T,VT,VI,VD} = VectorOfArrays{T,1,VT,VI,VD}`
116-
117-
### Appending data and resizing
118-
119-
A `VectorOfArrays` is grown by appending data to it. `resize!` can be used to shrink it, but not to grow it (the size of the additional element arrays would be unknown):
120-
121-
```
122-
length(resize!(VA, 1)) == 1
123-
```
124-
125-
but
126-
127-
```
128-
resize!(VA, 4)
129-
```
130-
131-
will fail.
132-
133-
Note: The vector returned by `flatview(VA)` *must not* be resized directly, doing so would break the internal consistency of `VA`.
134-
135-
136-
## Allocation free element access
137-
138-
Element access via `getindex` returns (possibly reshaped) instances of `SubArray` for both `ArrayOfSimilarArrays` and `VectorOfArrays`. Usually this is not a problem, but frequent allocation of a large number of views can become a limiting factor in multi-threaded applications.
139-
140-
Both types support `UnsafeArrays.@uviews` for allocation-free getindex:
141-
142-
```julia
143-
using UnsafeArrays
144-
145-
A = nestedview(rand(2,3,4,5), 2)
146-
147-
isbits(A[2,2]) == false
148-
149-
@uviews A begin
150-
isbits(A[2,2]) == true
151-
end
152-
```
153-
154-
As always, `UnsafeArray`s should be used with great care: The pointer-based bitstype
155-
views *must not* be allowed to escape the `@uviews` scope, and internal data of `A` *must not* be reallocated (e.g. due to a `push!` or `append!` on `A`) while the `@uviews` scope is active.
18+
* [Documentation for stable version](https://oschulz.github.io/ArraysOfArrays.jl/stable)
19+
* [Documentation for development version](https://oschulz.github.io/ArraysOfArrays.jl/dev)

‎docs/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
build/
2+
site/

‎docs/Project.toml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
4+
5+
[compat]
6+
Documenter = "~0.20"

‎docs/make.jl

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Use
2+
#
3+
# DOCUMENTER_DEBUG=true julia --color=yes make.jl local [fixdoctests]
4+
#
5+
# for local builds.
6+
7+
using Documenter
8+
using ArraysOfArrays
9+
10+
makedocs(
11+
sitename = "ArraysOfArrays",
12+
modules = [ArraysOfArrays],
13+
format = :html,
14+
pages=[
15+
"Home" => "index.md",
16+
"API" => "api.md",
17+
"LICENSE" => "LICENSE.md",
18+
],
19+
doctest = ("fixdoctests" in ARGS) ? :fix : true,
20+
html_prettyurls = !("local" in ARGS),
21+
html_canonical = "https://oschulz.github.io/ArraysOfArrays.jl/stable/",
22+
)
23+
24+
deploydocs(
25+
repo = "github.com/oschulz/ArraysOfArrays.jl.git"
26+
)

‎docs/src/LICENSE.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# LICENSE
2+
3+
```@eval
4+
using Markdown
5+
Markdown.parse_file(joinpath(@__DIR__, "..", "..", "LICENSE.md"))
6+
```

‎docs/src/api.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# API
2+
3+
```@meta
4+
CurrentModule = ArraysOfArrays
5+
DocTestSetup = quote
6+
using ArraysOfArrays
7+
end
8+
```
9+
10+
## Types
11+
12+
```@index
13+
Order = [:type]
14+
```
15+
16+
## Functions
17+
18+
```@index
19+
Order = [:function]
20+
```
21+
22+
# Documentation
23+
24+
```@autodocs
25+
Modules = [ArraysOfArrays]
26+
Order = [:type, :function]
27+
```

0 commit comments

Comments
 (0)