Update docs

README.md

@@ -7,94 +7,22 @@ Interval Sets for Julia
 [![Coverage](https://codecov.io/gh/JuliaMath/IntervalSets.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMath/IntervalSets.jl)
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
-This package represents intervals of an ordered set. For an interval
-spanning from `a` to `b`, all values `x` that lie between `a` and `b`
-are defined as being members of the interval.
-
-Currently this package defines one concrete type, `Interval`.
-These define the set spanning from `a` to `b`, meaning the
-interval is defined as the set `{x}` satisfying `a ≤ x ≤ b`. This is
-sometimes written `[a,b]` (mathematics syntax, not Julia syntax) or
-`a..b`.
-
-Optionally, `Interval{L,R}` can represent open and half-open intervals. The type
-parameters `L` and `R` correspond to the left and right endpoint respectively.
-The notation `ClosedInterval` is short for `Interval{:closed,:closed}`, while `OpenInterval` is short for `Interval{:open,:open}`. For example, the interval `Interval{:open,:closed}` corresponds to the set `{x}` satisfying `a < x ≤ b`.
-
-## Usage
-
-You can construct `ClosedInterval`s in a variety of ways:
+## Quick start
 
 ```julia
 julia> using IntervalSets
 
-julia> ClosedInterval{Float64}(1,3)
+julia> i1 = 1.0 .. 3.0
 1.0 .. 3.0
 
-julia> 0.5..2.5
-0.5 .. 2.5
-
-julia> 1.5±1
-0.5 .. 2.5
-```
-
-Similarly, you can construct `OpenInterval`s and `Interval{:open,:closed}`s, and `Interval{:closed,:open}`:
-```julia
-julia> OpenInterval{Float64}(1,3)
-1.0 .. 3.0 (open)
-
-julia> OpenInterval(0.5..2.5)
-0.5 .. 2.5 (open)
-
-julia> Interval{:open,:closed}(1,3)
-1 .. 3 (open-closed)
-```
-
-The `±` operator may be typed as `\pm<TAB>` (using Julia's LaTeX
-syntax tab-completion).
-
-Intervals also support the expected set operations:
-
-```julia
-julia> 1.75 ∈ 1.5±1  # \in<TAB>; can also use `in`
-true
-
-julia> 0 ∈ 1.5±1
-false
-
-julia> 1 ∈ OpenInterval(0..1)
-false
-
-julia> intersect(1..5, 3..7)   # can also use `a ∩ b`, where the symbol is \cap<TAB>
-3 .. 5
+julia> i2 = OpenInterval(0..4)
+0 .. 4 (open)
 
-julia> isempty(intersect(1..5, 10..11))
+julia> i1 ⊆ i2
 true
 
-julia> (0.25..5) ∪ (3..7.4)    # \cup<TAB>; can also use union()
-0.25 .. 7.4
-
-julia> isclosedset(0.5..2.0)
-true
-
-julia> isopenset(OpenInterval(0.5..2.5))
-true
-
-julia> isleftopen(2..3)
+julia> i2 ⊆ i1
 false
 ```
 
-When computing the union, the result must also be an interval:
-```julia
-julia> (0.25..5) ∪ (6..7.4)
-ERROR: ArgumentError: Cannot construct union of disjoint sets.
-Stacktrace:
- [1] union(d1::ClosedInterval{Float64}, d2::ClosedInterval{Float64})
-   @ IntervalSets ~/.julia/dev/IntervalSets/src/interval.jl:127
- [2] top-level scope
-   @ REPL[2]:1
-```
-
-### Importing the .. operator
-
-To import the `..` operator, use `import IntervalSets: (..)`. The parantheses are necessary to avoid parsing issues.
+Please refer to the [documentation](https://JuliaMath.github.io/IntervalSets.jl/stable) for comprehensive guides and examples.

docs/src/index.md

@@ -1,6 +1,12 @@
 # IntervalSets.jl
 
-A Julia package implementing [IntervalSets](https://en.wikipedia.org/wiki/Quaternion).
+A Julia package implementing [interval sets](https://en.wikipedia.org/wiki/Interval_(mathematics)).
+
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaMath.github.io/IntervalSets.jl/stable)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaMath.github.io/IntervalSets.jl/dev)
+[![Build Status](https://github.com/JuliaMath/IntervalSets.jl/workflows/CI/badge.svg)](https://github.com/JuliaMath/IntervalSets.jl/actions)
+[![Coverage](https://codecov.io/gh/JuliaMath/IntervalSets.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMath/IntervalSets.jl)
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
 !!! note "Documentation"
     The documentation is still work in progress.
@@ -13,3 +19,62 @@ A Julia package implementing [IntervalSets](https://en.wikipedia.org/wiki/Quater
 ```
 pkg> add IntervalSets
 ```
+
+## Quick start
+
+```@repl
+using IntervalSets
+i1 = 1.0 .. 3.0
+i2 = OpenInterval(0..4)
+i1 ⊆ i2
+i2 ⊆ i1
+```
+
+Currently this package defines one concrete type, [`Interval`](@ref).
+These define the set spanning from `a` to `b`, meaning the interval is defined as the set ``\{x \ | \ a ≤ x ≤ b\}``.
+This is sometimes written ``[a,b]`` (mathematics syntax, not Julia syntax) or ``a..b``.
+
+Optionally, `Interval{L,R}` can represent open and half-open intervals.
+The type parameters `L` and `R` correspond to the left and right endpoint respectively.
+The notation [`ClosedInterval`](@ref) is short for `Interval{:closed,:closed}`,
+while [`OpenInterval`](@ref) is short for `Interval{:open,:open}`.
+For example, the interval `Interval{:open,:closed}` corresponds to the set ``\{x \ | \ a < x ≤ b\}``.
+
+## More examples
+
+```@setup more
+using IntervalSets
+```
+
+### Constructors
+```@repl more
+ClosedInterval{Float64}(1,3)
+OpenInterval{Float64}(1,3)
+Interval{:open, :closed}(1,3)
+0.5..2.5
+1.5 ± 1
+Interval{:open,:closed}(1,3)
+OpenInterval(0.5..2.5)  # construct `OpenInterval` from `ClosedInterval`
+```
+
+The [`±`](@ref) operator may be typed as `\pm<TAB>` (using Julia's LaTeX syntax tab-completion).
+
+### Set operations
+
+```@repl
+1.75 ∈ 1.5±1  # \in<TAB>; can also use `in`
+0 ∈ 1.5±1
+1 ∈ OpenInterval(0..1)
+intersect(1..5, 3..7)   # can also use `a ∩ b`, where the symbol is \cap<TAB>
+isempty(intersect(1..5, 10..11))
+(0.25..5) ∪ (3..7.4)  # \cup<TAB>; can also use `union()`
+isclosedset(0.5..2.0)
+isopenset(OpenInterval(0.5..2.5))
+isleftopen(2..3)
+(0.25..5) ∪ (6..7.4)  # union of interval must be an interval
+```
+
+### Importing the `..` operator
+
+To import the [`..`](@ref) operator, use `import IntervalSets: (..)`.
+The parantheses are necessary to avoid parsing issues.

src/IntervalSets.jl

@@ -241,7 +241,7 @@ clamp(t, i::TypedEndpointsInterval{:closed,:closed}) =
 """
     mod(x, i::AbstractInterval)
 
-Find `y` in the `i` interval such that ``x ≡ y (mod w)``, where `w = width(i)`.
+Find `y` in the `i` interval such that ``x ≡ y \\pmod w``, where `w = width(i)`.
 
 # Examples