improve Spherical docs (#68)

Co-authored-by: Waldir Pimenta <waldyrious@gmail.com>

Author: jw3126

Project.toml

@@ -3,17 +3,18 @@ uuid = "150eb455-5306-5404-9cee-2592286d6298"
 version = "0.6.0"
 
 [deps]
-StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
 [compat]
 StaticArrays = "0.11,0.12"
 julia = "1"
 
 [extras]
-Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
 [targets]
-test = ["Test", "ForwardDiff", "Unitful"]
+test = ["Test", "ForwardDiff", "Unitful", "Documenter"]

docs/src/note.txt

@@ -0,0 +1 @@
+this directory must exist for running doctests

src/coordinatesystems.jl

@@ -73,6 +73,25 @@ Base.convert(::Type{Polar}, v::AbstractVector) = PolarFromCartesian()(v)
 #############################
 """
 Spherical(r, θ, ϕ) - 3D spherical coordinates
+
+There are many Spherical coordinate conventions and this library uses a somewhat exotic one.
+Given a vector `v` with Cartesian coordinates `xyz`, let `v_xy = [x,y,0]` be the orthogonal projection of `v` on the `xy` plane.
+
+* `r` is the radius. It is given by `norm(v, 2)`.
+* `θ` is the azimuth. It is the angle from the x-axis to `v_xy`
+* `ϕ` is the latitude. It is the angle from `v_xy` to `v`.
+
+```jldoctest
+julia> using CoordinateTransformations
+
+julia> v = randn(3);
+
+julia> sph = SphericalFromCartesian()(v);
+
+julia> r = sph.r; θ=sph.θ; ϕ=sph.ϕ;
+
+julia> v ≈ [r * cos(θ) * cos(ϕ), r * sin(θ) * cos(ϕ), r*sin(ϕ)]
+true
 """
 struct Spherical{T,A}
     r::T

test/runtests.jl

@@ -4,9 +4,12 @@ using CoordinateTransformations
 using ForwardDiff: Dual, partials
 using StaticArrays
 using Unitful
+using Documenter: doctest
+
 
 @testset "CoordinateTransformations" begin
 
+    doctest(CoordinateTransformations)
     include("core.jl")
     include("coordinatesystems.jl")
     include("affine.jl")