Improved documentation

Restructure documentation to keep the main page short and with the most important
information. Move other documentation to its oen pages and cross reference.

docs/make.jl

@@ -15,8 +15,11 @@ makedocs(sitename = "JetReconstruction.jl",
              "Examples" => "examples.md",
              "EDM4hep" => "EDM4hep.md",
              "Visualisation" => "visualisation.md",
-             "Reference" => Any["Public API" => "lib/public.md",
-                                "Internal API" => "lib/internal.md"]
+             "Particle Inputs" => "particles.md",
+             "Reconstruction Strategies" => "strategy.md",
+             "Reference Docs" => Any["Public API" => "lib/public.md",
+                                "Internal API" => "lib/internal.md"],
+             "Extras" => Any["Serialisation" => "extras/serialisation.md"]
          ])
 
 deploydocs(repo = "github.com/JuliaHEP/JetReconstruction.jl.git",

docs/src/EDM4hep.md

@@ -1,8 +1,37 @@
-# EDM4hep
+# EDM4hep Inputs
 
-Extension functionality to read EDM4hep ReconstructedParticles
+Extension functionality to read EDM4hep ReconstructedParticles, using the
+[EDM4hep.jl](https://github.com/peremato/EDM4hep.jl) package.
 
-## Index
+## Examples
+
+EDM4hep `ReconstructedParticles` can be used as direct input into jet
+reconstruction.
+
+A number of working examples are maintained in the [EDM4hep examples
+directory](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples/EDM4hep)
+of the package's `examples`.
+
+Here is a snippet that shows the main steps:
+
+```julia
+using EDM4hep
+using EDM4hep.RootIO
+using JetReconstruction
+
+# Change this to something that works on your system
+input_file = joinpath("directory", "EDM4hep.root")
+reader = RootIO.Reader(input_file)
+events = RootIO.get(reader, "events")
+
+evt = events[1]
+
+recps = RootIO.get(reader, evt, "ReconstructedParticles")
+
+cs = jet_reconstruct(recps; algorithm = JetAlgorithm.Durham)
+```
+
+## Function Index
 
 ```@index
 Pages = ["EDM4hep.md"]

docs/src/examples.md

@@ -1,7 +1,9 @@
 # Jet Reconstruction Examples
 
 The Jet Reconstruction package has a number of example files that show how to
-usage.
+usage. These are in the `examples` subdirectory of the package and can be
+browsed directly on
+[GitHub](https://github.com/JuliaHEP/JetReconstruction.jl/tree/main/examples).
 
 *Note:* because of extra dependencies in these scripts, one must use the
 `Project.toml` file in the `examples` directory.
@@ -58,4 +60,4 @@ showing how the jets merge from their different constituents.
 
 The `examples/EDM4hep` folder contains examples of using EDM4hep reconstructed
 particles as input to jet reconstruction. See the specific `README.md` file in
-that directory.
+that directory as well as [EDM4hep Inputs](@ref).

docs/src/extras/serialisation.md

@@ -0,0 +1,5 @@
+# Jet Serialisation
+
+The package provides methods such as `loadjets`, `loadjets!`, and `savejets`
+that one can use to save and load objects on/from disk easily in a very flexible
+format. See documentation for more.

docs/src/index.md

@@ -26,42 +26,22 @@ jet_reconstruct(particles; algorithm = JetAlgorithm.AntiKt, R = 1.0)
 or with some of the optional arguments,
 
 ```julia
-jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4, p = 0.5, recombine = +, strategy = RecoStrategy.Best)
+jet_reconstruct(particles; algorithm = JetAlgorithm.GenKt, R = 0.4, 
+                p = 0.5, recombine = +, strategy = RecoStrategy.Best)
 ```
 
-Where `particles` is a collection of 4-vector objects to reconstruct and the
-algorithm is either given explicitly or implied by the power value. For the case
-of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the algorithm
-(`JetAlgorithm.GenKt`) and `p` are needed. For the case of the Durham algorithm
-the `R` value is ignored.
+Where `particles` is a collection of 4-vector objects (see [Input Particle
+Types](@ref)) to reconstruct and the algorithm is either given explicitly or
+implied by the power value.
 
-The object returned is a [`ClusterSequence`](@ref), which internally tracks all
-merge steps.
-
-### Input Particle Types
-
-For the `particles` input to the reconstruction any one dimensional
-`AbstractArray{T, 1}` can be used, where the type `T` has to implement methods
-to extract the 4-vector components, viz, the following are required:
-
-- `JetReconstuction.px(particle::T)`
-- `JetReconstuction.py(particle::T)`
-- `JetReconstuction.pz(particle::T)`
-- `JetReconstuction.energy(particle::T)`
-
-Currently built-in supported types are
-[`LorentzVectorHEP`](https://github.com/JuliaHEP/LorentzVectorHEP.jl), the
-`PseudoJet` and `EEjet`s from this package, and `ReconstructedParticles` from
-[EDM4hep](https://github.com/peremato/EDM4hep.jl).
+For the case of generalised ``k_T`` (for ``pp`` and ``e^+e^-``) both the
+algorithm (`GenKt`, `EEKt`) and `p` are needed.
 
-If you require support for a different input collection type then ensure you
-define the `px()`, etc. methods *for your specific type* and *in the
-`JetReconstruction` package*. This use of what might be considered type piracy
-is blessed as long as you are en *end user* of the jet reconstruction package.
+The `R` value determines the cone size; in the case of the Durham algorithm the
+`R` value is ignored.
 
-If your type is used in several places or by different users, please consider
-writing a package extension that will support your type, following the model for
-EDM4hep in `ext/EDM4hepJets.jl`.
+The object returned is a [`ClusterSequence`](@ref), which internally tracks all
+merge steps and is used for [Inclusive and Exclusive Selections](@ref).
 
 ### Algorithm Types
 
@@ -76,37 +56,26 @@ Each known algorithm is referenced using a `JetAlgorithm` scoped enum value.
 | ``e^+e-`` ``k_\text{T}`` / Durham | `JetAlgorithm.Durham` | `R` value ignored and can be omitted |
 | generalised ``e^+e-`` ``k_\text{T}`` | `JetAlgorithm.EEKt` | For ``e^+e^-``, value of `p` must also be specified |
 
-### ``pp`` Algorithms
+#### ``pp`` Algorithms
 
 For the three ``pp`` algorithms with fixed `p` values, the `p` value can be
 given instead of the algorithm name. However, this should be considered
 *deprecated* and will be removed in a future release.
 
-## Strategy
-
-For the ``pp`` algorithms three strategies are available for the different
-algorithms, which can be specified by passing the named argument `strategy=...`.
-
-| Strategy Name | Notes | Interface |
-|---|---|---|
-| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` |
-| `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.
+### Strategy
 
-For ``e^+e^-`` algorithms particle densities are low, so the only implementation
-is of the same type as `N2Plain`.
+Generally one does not need to manually specify a strategy, but [Algorithm
+Strategy](@ref) describes how to do this, if desired.
 
 ## Inclusive and Exclusive Selections
 
 To obtain final jets both inclusive (``p_T`` cut) and exclusive (``n_{jets}`` or
 ``d_{ij}`` cut) selections are supported:
 
-- [inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)](@ref)
-- [exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)](@ref)
+- [`inclusive_jets(clusterseq::ClusterSequence, ptmin = 0.0)`](@ref)
+- [`exclusive_jets(clusterseq::ClusterSequence; dcut = nothing, njets = nothing)`](@ref)
+
+(For `exclusive_jets` either `dcut` or `njets` is needed, but not both.)
 
 ### Sorting
 
@@ -119,29 +88,7 @@ sorted_jets = sort!(inclusive_jets(cs::ClusterSequence; ptmin=5.0),
   by=JetReconstruction.energy, rev=true)
 ```
 
-## Plotting and Animation
-
-![illustration](assets/jetvis.png)
-
-To visualise the clustered jets as a 3d bar plot (see illustration above) we now
-use `Makie.jl`. See the `jetsplot` function in `ext/JetVisualisation.jl` and its
-documentation for more. There are two worked examples in the `examples`
-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
-`savejets` that one can use to save and load objects on/from disk easily in a
-very flexible format. See documentation for more.
-
-## Reference
+## References
 
 Although it has been developed further since the CHEP2023 conference, the CHEP
 conference proceedings,

docs/src/particles.md

@@ -0,0 +1,24 @@
+# Input Particle Types
+
+For the `particles` input to the reconstruction any one dimensional
+`AbstractArray{T, 1}` can be used, where the type `T` has to implement methods
+to extract the 4-vector components, viz, the following are required:
+
+- `JetReconstuction.px(particle::T)`
+- `JetReconstuction.py(particle::T)`
+- `JetReconstuction.pz(particle::T)`
+- `JetReconstuction.energy(particle::T)`
+
+Currently built-in supported types are
+[`LorentzVectorHEP`](https://github.com/JuliaHEP/LorentzVectorHEP.jl), the
+`PseudoJet` and `EEjet`s from this package, and `ReconstructedParticles` from
+[EDM4hep Inputs](@ref).
+
+If you require support for a different input collection type then ensure you
+define the `px()`, etc. methods *for your specific type* and *in the
+`JetReconstruction` package*. This use of what might be considered type piracy
+is blessed as long as you are en *end user* of the jet reconstruction package.
+
+If your type is used in several places or by different users, please consider
+writing a package extension that will support your type, following the model for
+EDM4hep in `ext/EDM4hepJets.jl`.

docs/src/strategy.md

@@ -0,0 +1,18 @@
+# Algorithm Strategy
+
+For the ``pp`` algorithms three strategies are available for the different
+algorithms, which can be specified by passing the named argument `strategy=...`
+to the reconstruction.
+
+| Strategy Name | Notes | Interface |
+|---|---|---|
+| `RecoStrategy.Best` | Dynamically switch strategy based on input particle density | `jet_reconstruct` |
+| `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.
+
+For ``e^+e^-`` algorithms particle densities are low, so the only implementation
+is of the same type as `N2Plain`.

docs/src/visualisation.md

@@ -2,7 +2,23 @@
 
 Documentation for visualisation interfaces extension module.
 
-## Index
+## Plotting and Animation
+
+![illustration](assets/jetvis.png)
+
+To visualise the clustered jets as a 3d bar plot (see illustration above)
+`Makie.jl` is used. See the `jetsplot` function in `ext/JetVisualisation.jl` and
+its documentation for more. There are two worked examples in the `examples`
+directory of this package.
+
+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 below for the
+many options that can be customised.
+
+## Function Index
 
 ```@index
 Pages = ["visualisation.md"]