Improved documentation

Add Documenter setup to use @autodocs to generate
all public and internal documentation.
Use @ref links to refer to methods and types in
main documentation pages.

Move get_all_ancestors() method to ClusterSequence
(it is not visualisation).

Add logo for the package!

Author: graeme-a-stewart

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JetReconstruction = "44e8cb2c-dfab-4825-9c70-d4808a591196"
+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 
 [compat]
 Documenter = "1.4"

docs/make.jl

@@ -1,7 +1,21 @@
 using Documenter
+using CairoMakie
 using JetReconstruction
 
-makedocs(sitename = "JetReconstruction.jl")
+push!(LOAD_PATH,"../ext/")
+
+include(joinpath(@__DIR__, "..", "ext", "JetVisualisation.jl"))
+
+makedocs(sitename = "JetReconstruction.jl",
+    pages = [
+        "Home" => "index.md",
+        "Examples" => "examples.md",
+        "Reference" => Any[
+            "Public API" => "lib/public.md",
+            "Internal API" => "lib/internal.md",
+            "Visualisation API" => "lib/visualisation.md",
+        ]
+        ],)
 
 deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git",
            push_preview = true)

docs/src/assets/logo.png

@@ -44,3 +44,8 @@ Similar to `visualise-jets.jl` this notebook will produce a visualisation of jet
 reconstruction in the browser. This is a 3D plot where all the initial energy
 deposits are visualised, with colours that indicate in which final cluster the
 deposit ended up in.
+
+## `animate-reconstruction.jl`
+
+Performs jet reconstruction and then produces and animation of the process,
+showing how the jets merge from their different constituents.

docs/src/assets/logo.svg

@@ -16,17 +16,16 @@ inclusive ``k_\text{T}``.
 
 ## Reconstruction Interface
 
-The main interface for reconstruction is:
+The main interface for reconstruction is [`jet_reconstruct`](@ref), called as, e.g.,
 
-```@docs
-jet_reconstruct(particles; p = -1, R = 1.0, recombine = +, strategy = RecoStrategy.Best)
+```julia
+jet_reconstruct(particles; p = -1, R = 1.0)
 ```
 
-The object returned is a `ClusterSequence`, which internally tracks all merge steps.
+Where `particles` is a collection of 4-vector objects to reconstruct.
 
-```@docs
-ClusterSequence
-```
+The object returned is a [`ClusterSequence`](@ref), which internally tracks all
+merge steps.
 
 ## Strategy
 
@@ -38,9 +37,12 @@ Three strategies are available for the different algorithms:
 | `RecoStrategy.N2Plain` | Global matching of particles at each interation (works well for low $N$) | `plain_jet_reconstruct` |
 | `RecoStrategy.N2Tiled` | Use tiles of radius $R$ to limit search space (works well for higher $N$) | `tiled_jet_reconstruct` |
 
-Generally one can use the `jet_reconstruct` interface, shown above, as the *Best* strategy safely as the overhead is extremely low. That interface supports a `strategy` option to switch to a different option.
+Generally one can use the `jet_reconstruct` interface, shown above, as the
+*Best* strategy safely as the overhead is extremely low. That interface supports
+a `strategy` option to switch to a different option.
 
-Another option, if one wishes to use a specific strategy, is to call that strategy's interface directly, e.g.,
+Another option, if one wishes to use a specific strategy, is to call that
+strategy's interface directly, e.g.,
 
 ```julia
 # For N2Plain strategy called directly
@@ -54,19 +56,8 @@ Note that there is no `strategy` option in these interfaces.
 To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
 ``d_{ij}`` cut) selections are supported:
 
-```@docs
-inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)
-```
-
-```@docs
-exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)
-```
-
-The number of exclusive jets passing a particular `dcut` can be obtained:
-
-```@docs
-n_exclusive_jets(clusterseq::ClusterSequence; dcut::AbstractFloat)
-```
+- [inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)](@ref)
+- [exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)](@ref)
 
 ### Sorting
 
@@ -79,7 +70,7 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
   by=JetReconstruction.energy, rev=true)
 ```
 
-## Plotting
+## Plotting and Animation
 
 ![illustration](assets/jetvis.png)
 
@@ -91,6 +82,10 @@ directory.
 The plotting code is a package extension and will load if the one of the `Makie`
 modules is loaded in the environment.
 
+The [`animatereco`](@ref) function will animate the reconstruction sequence, given a
+`ClusterSequence` object. See the function documentation for the many options
+that can be customised.
+
 ## Serialisation
 
 The package also provides methods such as `loadjets`, `loadjets!`, and

docs/src/examples.md

@@ -0,0 +1,23 @@
+# Jet Reconstruction Internal Documentation
+
+Documentation for `JetReconstruction.jl`'s internal methods and types.
+
+N.B. no guarantee is made of stability of these interfaces or types.
+
+```@meta
+CollapsedDocStrings = true
+```
+
+## Index
+
+```@index
+Pages = ["internal.md"]
+```
+
+## Public Interface
+
+```@autodocs
+Modules = [JetReconstruction]
+Public = false
+Order = [:function, :type]
+```

docs/src/index.md

@@ -0,0 +1,17 @@
+# Jet Reconstruction Public Documentation
+
+Documentation for `JetReconstruction.jl`'s public interfaces.
+
+## Index
+
+```@index
+Pages = ["public.md"]
+```
+
+## Public Methods and Types
+
+```@autodocs
+Modules = [JetReconstruction]
+Private = false
+Order = [:function, :type]
+```

docs/src/lib/internal.md

@@ -0,0 +1,16 @@
+# Jet Visualisation Documentation
+
+Documentation for visualisation interfaces extension module.
+
+## Index
+
+```@index
+Pages = ["visualisation.md"]
+```
+
+## Jet Visualisation Public Interfaces
+
+```@autodocs
+Modules = [JetVisualisation]
+Order = [:function]
+```

docs/src/lib/public.md

@@ -29,3 +29,8 @@ colours that indicate in which final cluster the deposit ended up in.
 This notebook will produce a visualisation of jet reconstruction in the browser.
 This is a 3D plot where all the initial energy deposits are visualised, with
 colours that indicate in which final cluster the deposit ended up in.
+
+## `animate-reconstruction.jl`
+
+Performs jet reconstruction and then produces and animation of the process,
+showing how the jets merge from their different constituents.