docs: add missing files

docs/src/examples/examples.md

@@ -0,0 +1,32 @@
+# Spectral fitting examples
+
+```@setup sf_examples 
+using SpectralFitting
+using Plots
+ENV["GKSwstype"]="nul"
+Plots.default(show=false)
+```
+
+Below are a number of examples illustrating how this package may be used.
+
+## Using the model library
+
+The model library details a model algebra (see [`AbstractSpectralModelKind`](@ref)) for composing models together. An example use of this may be to construct a complex model from a series of simpler models, and invoke the models on a given energy grid:
+
+```@example sf_examples 
+using SpectralFitting
+using Plots 
+
+model = PhotoelectricAbsorption() * (PowerLaw() + BlackBody()) 
+
+# define energy grid
+energy = collect(range(0.1, 12.0, 100))
+
+flux = invokemodel(energy, model)
+
+plot(energy[1:end-1], flux)
+```
+
+Note this energy grid may be arbitrarily spaced, but, like XSPEC, assumes the bins are contiguous, i.e. that the high energy limit of one bin is the low energy limit of the next.
+
+The full model library of available models is listed in [Model index](./models.md).

docs/src/reference.md

@@ -1,12 +1,5 @@
 # API reference
 
-## Energy and flux utility functions
-
-```@docs
-make_flux
-make_fluxes
-```
-
 ## Utility functions for defining new models
 
 ```@docs

docs/src/why-and-how.md

@@ -2,7 +2,7 @@
 
 SpectralFitting.jl is a package for fitting models to spectral data, similar to [XSPEC](https://heasarc.gsfc.nasa.gov/xanadu/xspec/), [Sherpa](https://sherpa.readthedocs.io/en/latest/ciao.html) or [ISIS](https://space.mit.edu/CXC/isis/).
 
-The rationale for this package is to provide a unanimous interface for different model libraries, and to leverage the bleeding edge advancements in computing that are available in Julia, including the rich statistics ecosystem, with [automatic-differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation) and [_speed_](https://julialang.org/benchmarks/).
+The rationale for this package is to provide a unanimous interface for different model libraries, and to leverage advancements in the computional methods that are available in Julia, including the rich statistics ecosystem, with [automatic-differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation) and [_speed_](https://julialang.org/benchmarks/).
 
 SpectralFitting aims to provide highly optimised and flexible fitting algorithms, along with a library of spectral models, for use in any field of Astronomy that concerns itself with spectral data.