Update docs on calibration/orientation

docs/src/api.md

@@ -93,8 +93,10 @@ read(filename::AbstractString, T::Type{AcousticsTriggerParameter})
 calibrate
 calibratetime
 combine
+Orientations
 floordist
 slew
+slerp
 ```
 
 ## Physics

docs/src/manual/calibration.md

 # Calibration
 
-It's implemented but not documented here yet. Check out the docs `calibrate`
-function's docstring!
+In general, data related to detector calibration are either stored in the
+database or in the [Calibration
+Archive](https://git.km3net.de/auxiliary_data/calibration).
 
+## Hits
+
+Hit calibration is implemented but not documented here yet. Check out the docs for [`calibrate()`](@ref).
+
+## Module Orientations
+
+Module orientation data is stored in ROOT files which are generated by the Jpp
+framework. The corresponding ROOT files, which are the output of the [dynamic
+calibration
+procedure](https://common.pages.km3net.de/jpp/Position_calibration.PDF), are
+stored in the [Calibration
+Archive](https://git.km3net.de/auxiliary_data/calibration) under
+`orientations/`.
+
+`KM3io.jl` extends the `Base.read` function with a method which reads the whole
+orientations file at once in an object of type [`Orientations`](@ref). This
+object can be called to calculate the orientation of a module (as a quaternion)
+for a given time, as long as the time is within the time range of the
+orientation data. The quaternions from the orientation data are interpolated for
+the given time using [`slerp()`](@ref).
+
+The following example shows how to read the orientation data and obtain the
+orientation quaternion for a module at a given time.
+
+```@example 1
+using KM3io, KM3NeTTestData
+
+o = read(datapath("calib", "KM3NeT_00000133_D_1.0.0_00017397_00017496_1.orientations.root"), Orientations)
+
+module_id = 817589211
+
+q = o(module_id,  1693408347)
+```