Refine documentation

Add more details on the main interface
Split examples into their own section

docs/make.jl

@@ -1,5 +1,4 @@
 using Documenter
 using JetReconstruction
 
-# makedocs(sitename="JetReconstruction.jl", modules = [JetReconstruction])
 makedocs(sitename = "JetReconstruction.jl")

docs/src/examples.md

@@ -0,0 +1,46 @@
+# Jet Reconstruction Examples
+
+The Jet Reconstruction package has a number of example files that show how to
+usage.
+
+*Note:* because of extra dependencies in these scripts, one must use the
+`Project.toml` file in the `examples` directory.
+
+## `jetreco.jl`
+
+This is a basic jet reconstruction example that shows how to call the package to
+perform a jet reconstruction, with different algorithms and (optionally)
+strategy, producing exclusive and inclusive jet selections.
+
+```sh
+julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Plain test/data/events.hepmc3
+...
+julia --project=. examples/jetreco.jl --maxevents=100 --strategy=N2Tiled test/data/events.hepmc3
+...
+```
+
+There are options to explicitly set the algorithm (use `--help` to see these).
+
+## `instrumented-jetreco.jl`
+
+This is a more sophisticated example that allows performance measurements to be
+made of the reconstruction, as well as profiling (flamegraphs and memory
+profiling). Use the `--help` option to see usage. e.g., to extract timing
+performance for the AntiKt algorithm using the tiled strategy:
+
+```sh
+julia --project instrumented-jetreco.jl -S N2Tiled -A AntiKt --nsamples 100 ../test/data/events.hepmc3
+```
+
+## `visualise-jets.jl`
+
+This script will produce a PNG/PDF showing the results of a jet reconstruction.
+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.
+
+## `visualise-jets.ipynb`
+
+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.

docs/src/index.md

@@ -1,4 +1,4 @@
-# JetReconstruction.jl
+# Jet Reconstruction
 
 This package implements sequential Jet Reconstruction (clustering) algorithms,
 which are used in high-energy physics as part of event reconstruction for $pp$
@@ -11,7 +11,7 @@ Algorithms used are based on the C++ FastJet package (<https://fastjet.fr>,
 [arXiv:1111.6097](https://arxiv.org/abs/1111.6097)), reimplemented natively in
 Julia.
 
-The algorithms include anti-``{k}_\text{T}``, Cambridge/Aachen and inclusive ``k_\text{T}``.
+The algorithms include ``\text{anti}-{k}_\text{T}``, Cambridge/Aachen and inclusive ``k_\text{T}``.
 
 ## Reconstruction Interface
 
@@ -78,30 +78,6 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
   by=JetReconstruction.energy, rev=true)
 ```
 
-## Examples
-
-In the examples directory there are a number of example scripts.
-
-See the `jetreco.jl` script for an example of how to call jet reconstruction.
-
-```sh
-julia --project=. examples/jetreco.jl --maxevents=100 --nsamples=1 --strategy=N2Plain test/data/events.hepmc3
-...
-julia --project=. examples/jetreco.jl --maxevents=100 --nsamples=1 --strategy=N2Tiled test/data/events.hepmc3
-...
-```
-
-There are options to explicitly set the algorithm (use `--help` to see these).
-
-The example also shows how to use `JetReconstruction.HepMC3` to read HepMC3
-ASCII files (via the `read_final_state_particles()` wrapper).
-
-Further examples, which show visualisation, timing measurements, profiling, etc.
-are given - see the `README.md` file in the examples directory.
-
-Note that due to additional dependencies the `Project.toml` file for the
-examples is different from the package itself.
-
 ## Plotting
 
 ![illustration](assets/jetvis.png)
@@ -143,7 +119,7 @@ should be cited if you use this package:
 }
 ```
 
-The original paper on arXiv is:
+The original paper on [arXiv](https://arxiv.org/abs/2309.17309) is:
 
 ```bibtex
 @misc{stewart2023polyglot,

src/GenericAlgo.jl

@@ -5,7 +5,7 @@ Reconstructs jets from a collection of particles using a specified algorithm and
 strategy
 
 # Arguments
-- `particles`: A collection of particles used for jet reconstruction.
+- `particles`: A collection of particles used for jet reconstruction. 
 - `p=-1`: The power value used for the distance measure for generalised k_T,
   which maps to a particular reconstruction algorithm (-1 = AntiKt, 0 =
   Cambridge/Aachen, 1 = Kt).
@@ -19,6 +19,18 @@ strategy
 A cluster sequence object containing the reconstructed jets and the merging
 history.
 
+# Details
+
+## `particles` argument
+Any type that supplies the methods `pt2()`, `phi()`, `rapidity()`, `px()`,
+`py()`, `pz()`, `energy()` (in the `JetReconstruction` namespace) can be used.
+This includes `LorentzVector`, `LorentzVectorCyl`, and `PseudoJet`, for which
+these methods are already predefined in the `JetReconstruction` namespace.
+
+## `recombine` argument
+The `recombine` argument is the function used to merge pairs of particles. The
+default is simply `+(jet1,jet2)`, i.e. 4-momenta addition or the *E*-scheme.
+
 # Example
 ```julia
 jet_reconstruct(particles; p = -1, R = 0.4)