docs: Plotting with Makie.jl

docs/Project.toml

@@ -1,2 +1,7 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+# TODO: update when https://github.com/MakieOrg/Makie.jl/pull/5137 merged
+CairoMakie = "0.15.3"

docs/src/examples.md

@@ -40,72 +40,78 @@ Also, using `DynamicQuantities.Constants`, we were able to obtain the (dimension
 Let's solve a simple projectile motion problem.
 First load the `DynamicQuantities` module:
 
-```julia
+```@example projectile
 using DynamicQuantities
 ```
 
 Set up initial conditions as quantities:
 
-```julia
+```@example projectile
 # Can explicitly import units:
 using DynamicQuantities: km, m, s, min
 
 y0 = 10km
 v0 = 250m/s
 θ = deg2rad(60)
 g = 9.81m/s^2
+nothing # hide
 ```
 
 Next, we use trig functions to calculate x and y components of initial velocity.
 `vx0` is the x component and
 `vy0` is the y component:
 
-```julia
+```@example projectile
 vx0 = v0 * cos(θ)
 vy0 = v0 * sin(θ)
+nothing # hide
 ```
 
 Next, let's create a time vector from 0 seconds to 1.3 minutes.
 Note that these are the same dimension (time), so it's fine to treat
 them as dimensionally equivalent!
 
-```julia
+```@example projectile
 t = range(0s, 1.3min, length=100)
+nothing # hide
 ```
 
 Next, use kinematic equations to calculate x and y as a function of time.
 `x(t)` is the x position at time t, and
 `y(t)` is the y position:
 
-```julia
+```@example projectile
 x(t) = vx0*t
 y(t) = vy0*t - 0.5*g*t^2 + y0
+nothing # hide
 ```
 
 These are functions, so let's evaluate them:
 
-```julia
+```@example projectile
 x_si = x.(t)
 y_si = y.(t)
+nothing # hide
 ```
 
 These are regular vectors of quantities
 with `Dimensions` for physical dimensions.
 
-Next, let's plot the trajectory.
-First convert to km and strip units:
+Next, let's plot the trajectory. We will use [Makie.jl](https://docs.makie.org/) for its nice unit support:
 
-```julia
-x_km = ustrip.(x_si .|> us"km")
-y_km = ustrip.(y_si .|> us"km")
-```
+```@example projectile
+using CairoMakie
 
-Now, we plot:
+# Convert to kilometers first
+x_km = x_si .|> us"km"
+y_km = y_si .|> us"km"
 
-```julia
-plot(x_km, y_km, label="Trajectory", xlabel="x [km]", ylabel="y [km]")
+# Display
+lines(x_km, y_km; label="Trajectory", axis=(xlabel="x [km]", ylabel="y [km]"))
 ```
 
+See [Makie.jl > Dimension conversions](https://docs.makie.org/stable/explanations/dim-converts#Dimension-conversions) for more.
+
 ## 3. Using dimensional angles
 
 Say that we wish to track angles as a unit, rather than assume