From 8714c05e5735833ad1c2acfe39351a6f938d168e Mon Sep 17 00:00:00 2001
From: Brandon Flores <bsflores@wisc.edu>
Date: Mon, 11 Nov 2024 16:21:27 -0600
Subject: [PATCH] Updated Documenter documentation for Quaternions.jl extension

---
 docs/Project.toml                    |  1 +
 docs/make.jl                         |  6 ++--
 docs/src/api/extensions.md           | 11 +++++++
 docs/src/extensions.md               | 46 ++++++++++++++++++++++++++--
 ext/CliffordNumbersQuaternionsExt.jl |  5 +--
 5 files changed, 62 insertions(+), 7 deletions(-)
 create mode 100644 docs/src/api/extensions.md

diff --git a/docs/Project.toml b/docs/Project.toml
index 3ccd66d..0ef91e8 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,3 +1,4 @@
 [deps]
 CliffordNumbers = "3998ac73-6bd4-4031-8035-f167dd3ed523"
+Quaternions = "94ee1d12-ae83-5a48-8b1c-48b8ff168ae0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
diff --git a/docs/make.jl b/docs/make.jl
index 1461000..951d694 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,16 +1,18 @@
 using CliffordNumbers
+using Quaternions
 using Documenter
 
 import CliffordNumbers.BaseNumber
 
-DocMeta.setdocmeta!(CliffordNumbers, :DocTestSetup, :(using CliffordNumbers); recursive=true)
+using_directives = :(using CliffordNumbers; using Quaternions)
+DocMeta.setdocmeta!(CliffordNumbers, :DocTestSetup, using_directives; recursive=true)
 
 is_ci_env = (get(ENV, "CI", nothing) == true)
 @info "is_ci_env == $is_ci_env"
 
 makedocs(;
     sitename="CliffordNumbers.jl",
-    modules=[CliffordNumbers],
+    modules=[CliffordNumbers, Base.get_extension(CliffordNumbers, :CliffordNumberQuaternionsExt)],
     doctest=false,
     checkdocs = :exports,
     format=Documenter.HTML(;
diff --git a/docs/src/api/extensions.md b/docs/src/api/extensions.md
new file mode 100644
index 0000000..2f17db7
--- /dev/null
+++ b/docs/src/api/extensions.md
@@ -0,0 +1,11 @@
+# Extensions
+
+## [Quaternions.jl]
+
+```@docs
+(::Type{H})(::AbstractCliffordNumber{VGA(3)}) where H<:Quaternion
+Quaternions.slerp(::AbstractCliffordNumber{VGA(3)}, ::AbstractCliffordNumber{VGA(3)}, ::Real)
+Quaternions.slerp(::AbstractCliffordNumber{VGA(3)}, ::Quaternion, ::Real)
+```
+
+[Quaternions.jl]:   https://github.com/JuliaGeometry/Quaternions.jl
diff --git a/docs/src/extensions.md b/docs/src/extensions.md
index 7366bad..83ef8a0 100644
--- a/docs/src/extensions.md
+++ b/docs/src/extensions.md
@@ -3,9 +3,48 @@
 CliffordNumbers.jl provides some extensions to allow for interoperability with other packages which
 we anticipate to be commonly used alongside it.
 
-!!! note
-    Extensions require Julia 1.9; support for previous versions will be dropped with the 0.2.0
-    release of CliffordNumbers.jl.
+## [Quaternions.jl]
+
+[Quaternions.jl] provides the `Quaternion` type.
+
+This extension treats `Quaternion{T}` as identical to `EvenCliffordNumber{VGA(3),T,4}`, and each 
+type can be constructed from the other. This also extends to `AbstractCliffordNumber{VGA(3)}`.
+
+```julia-repl
+julia> q = Quaternion(0, 1, 2, 3)
+Quaternion{Int64}(0, 1, 2, 3)
+
+julia> e = EvenCliffordNumber{VGA(3)}(q)
+4-element EvenCliffordNumber{VGA(3), Int64}:
+1e₁e₂ + 2e₁e₃ + 3e₂e₃
+
+julia> Quaternion(e)
+Quaternion{Int64}(0, 1, 2, 3)
+
+julia> KVector{2,VGA(3)}(q)
+3-element KVector{2, VGA(3), Int64}:
+1e₁e₂ + 2e₁e₃ + 3e₂e₃
+```
+However, conversion can fail if the target type cannot contain the result:
+```
+julia> convert(KVector{2,VGA(3)}, q)
+ERROR: InexactError: convert(KVector{2, VGA(3)}, EvenCliffordNumber{VGA(3), Int64}(0, 1, 2, 3))
+...
+```
+
+Promotion attempts to preserve the semantics of CliffordNumbers.jl, and therefore prefers to return
+an `AbstractCliffordNumber{VGA(3)}`.
+
+```julia-repl
+julia> promote_type(EvenCliffordNumber{VGA(3),Int}, QuaternionF64)
+EvenCliffordNumber{VGA(3), Float64, 4}
+
+julia> promote_type(KVector{2,VGA(3),Int}, QuaternionF64)
+EvenCliffordNumber{VGA(3), Float64, 4}
+
+julia> promote_type(KVector{1,VGA(3),Int}, QuaternionF64)
+CliffordNumber{VGA(3), Float64, 8}
+```
 
 ## [Unitful.jl]
 
@@ -34,4 +73,5 @@ julia> KVector{1, VGA(3)}(1, 2, 3) * 1.5u"m"
 
 Supported operations include the geometric product and wedge product.
 
+[Quaternions.jl]:   https://github.com/JuliaGeometry/Quaternions.jl
 [Unitful.jl]: https://github.com/PainterQubits/Unitful.jl
diff --git a/ext/CliffordNumbersQuaternionsExt.jl b/ext/CliffordNumbersQuaternionsExt.jl
index 70a9f27..bc26950 100644
--- a/ext/CliffordNumbersQuaternionsExt.jl
+++ b/ext/CliffordNumbersQuaternionsExt.jl
@@ -28,6 +28,9 @@ function convert(::Type{C}, q::Quaternion) where C<:AbstractCliffordNumber{VGA(3
 end
 
 #---Conversion to quaternions----------------------------------------------------------------------#
+
+(::Type{H})(c::EvenCliffordNumber{VGA(3)}) where H<:Quaternion = H(Tuple(c)...)
+
 """
     Quaternion(c::AbstractCliffordNumber{VGA(3)})
     Quaternion{T}(c::AbstractCliffordNumber{VGA(3)})
@@ -39,8 +42,6 @@ Any odd-grade coefficients of `c` are lost.
 If loss of odd-grade coefficients should throw an error, use `convert(Quaternion, c)` or
 `convert(Quaternion{T}, c)` instead of the constructor.
 """
-(::Type{H})(c::EvenCliffordNumber{VGA(3)}) where H<:Quaternion = H(Tuple(c)...)
-
 function (::Type{H})(c::AbstractCliffordNumber{VGA(3)}) where H<:Quaternion
     return H(EvenCliffordNumber{VGA(3)}(c))
 end