Merge pull request #93 from abhro/docs

Documentation website and docstrings

Author: sjkelly

.gitignore

@@ -4,3 +4,5 @@
 
 *Manifest.toml
 *.swp
+
+/docs/build

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,10 @@
+using Documenter
+using CoordinateTransformations
+
+makedocs(
+    sitename = "CoordinateTransformations.jl",
+    pages = [
+        "Introduction" => "index.md",
+        "API" => "api.md",
+    ],
+)

docs/src/api.md

@@ -0,0 +1,7 @@
+# CoordinateTransformations.jl documentation
+
+## API Reference
+
+```@autodocs
+Modules = [CoordinateTransformations]
+```

docs/src/index.md

@@ -0,0 +1 @@
+# CoordinateTransformations.jl

src/affine.jl

@@ -2,8 +2,8 @@ abstract type AbstractAffineMap <: Transformation end
 
 """
     Translation(v) <: AbstractAffineMap
-    Translation(dx, dy)       (2D)
-    Translation(dx, dy, dz)   (3D)
+    Translation(dx, dy)         # 2D
+    Translation(dx, dy, dz)     # 3D
 
 Construct the `Translation` transformation for translating Cartesian points by
 an offset `v = (dx, dy, ...)`
@@ -215,8 +215,8 @@ transform_deriv(trans::AffineMap, x) = trans.linear
 
 Create an Affine transformation that approximately maps the `from` points to the `to` points.
 At least `n+1` non-degenerate points are required to map an `n`-dimensional space.
-If there are more points than this, the transformation will be over-determined and a least-squares
-solution will be computed.
+If there are more points than this, the transformation will be over-determined
+and a least-squares solution will be computed.
 """
 function AffineMap((from_points,to_points)::Pair)
     M = column_matrix(to_points) * pinv(column_matrix(from_points, 1))

src/coordinatesystems.jl

@@ -2,7 +2,9 @@
 ### 2D Coordinate systems ###
 #############################
 """
-`Polar{T,A}(r::T, θ::A)` - 2D polar coordinates
+    Polar{T,A}(r::T, θ::A)
+
+2D polar coordinates
 """
 struct Polar{T,A}
     r::T
@@ -18,7 +20,9 @@ function Polar(r, θ)
 end
 
 """
-`Polar{T,T}(x::AbstractVector)` - 2D polar coordinates from an AbstractVector of length 2
+    Polar{T,T}(x::AbstractVector)
+
+2D polar coordinates from an AbstractVector of length 2
 """
 function Polar(x::AbstractVector)
     return PolarFromCartesian()(x)
@@ -27,9 +31,17 @@ end
 Base.show(io::IO, x::Polar) = print(io, "Polar(r=$(x.r), θ=$(x.θ) rad)")
 Base.isapprox(p1::Polar, p2::Polar; kwargs...) = isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...)
 
-"`PolarFromCartesian()` - transformation from `AbstractVector` of length 2 to `Polar` type"
+"""
+    PolarFromCartesian()
+
+Transformation from `AbstractVector` of length 2 to `Polar` type
+"""
 struct PolarFromCartesian <: Transformation; end
-"`CartesianFromPolar()` - transformation from `Polar` type to `SVector{2}` type"
+"""
+    CartesianFromPolar()
+
+Transformation from `Polar` type to `SVector{2}` type
+"""
 struct CartesianFromPolar <: Transformation; end
 
 Base.show(io::IO, trans::PolarFromCartesian) = print(io, "PolarFromCartesian()")
@@ -79,10 +91,13 @@ Base.convert(::Type{Polar}, v::AbstractVector) = PolarFromCartesian()(v)
 ### 3D Coordinate Systems ###
 #############################
 """
-Spherical(r, θ, ϕ) - 3D spherical coordinates
+    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.
+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`
@@ -95,10 +110,11 @@ julia> v = randn(3);
 
 julia> sph = SphericalFromCartesian()(v);
 
-julia> r = sph.r; θ=sph.θ; ϕ=sph.ϕ;
+julia> r = sph.r; θ = sph.θ; ϕ = sph.ϕ;
 
-julia> v ≈ [r * cos(θ) * cos(ϕ), r * sin(θ) * cos(ϕ), r*sin(ϕ)]
+julia> v ≈ [r * cos(θ) * cos(ϕ), r * sin(θ) * cos(ϕ), r * sin(ϕ)]
 true
+```
 """
 struct Spherical{T,A}
     r::T
@@ -118,7 +134,9 @@ Base.show(io::IO, x::Spherical) = print(io, "Spherical(r=$(x.r), θ=$(x.θ) rad,
 Base.isapprox(p1::Spherical, p2::Spherical; kwargs...) = isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.ϕ, p2.ϕ; kwargs...)
 
 """
-Cylindrical(r, θ, z) - 3D cylindrical coordinates
+    Cylindrical(r, θ, z)
+
+3D cylindrical coordinates
 """
 struct Cylindrical{T,A}
     r::T
@@ -137,17 +155,41 @@ end
 Base.show(io::IO, x::Cylindrical) = print(io, "Cylindrical(r=$(x.r), θ=$(x.θ) rad, z=$(x.z))")
 Base.isapprox(p1::Cylindrical, p2::Cylindrical; kwargs...) = isapprox(p1.r, p2.r; kwargs...) && isapprox(p1.θ, p2.θ; kwargs...) && isapprox(p1.z, p2.z; kwargs...)
 
-"`SphericalFromCartesian()` - transformation from 3D point to `Spherical` type"
+"""
+    SphericalFromCartesian()
+
+Transformation from 3D point to `Spherical` type
+"""
 struct SphericalFromCartesian <: Transformation; end
-"`CartesianFromSpherical()` - transformation from `Spherical` type to `SVector{3}` type"
+"""
+    CartesianFromSpherical()
+
+Transformation from `Spherical` type to `SVector{3}` type
+"""
 struct CartesianFromSpherical <: Transformation; end
-"`CylindricalFromCartesian()` - transformation from 3D point to `Cylindrical` type"
+"""
+    CylindricalFromCartesian()
+
+Transformation from 3D point to `Cylindrical` type
+"""
 struct CylindricalFromCartesian <: Transformation; end
-"`CartesianFromCylindrical()` - transformation from `Cylindrical` type to `SVector{3}` type"
+"""
+    CartesianFromCylindrical()
+
+Transformation from `Cylindrical` type to `SVector{3}` type
+"""
 struct CartesianFromCylindrical <: Transformation; end
-"`CylindricalFromSpherical()` - transformation from `Spherical` type to `Cylindrical` type"
+"""
+    CylindricalFromSpherical()
+
+Transformation from `Spherical` type to `Cylindrical` type
+"""
 struct CylindricalFromSpherical <: Transformation; end
-"`SphericalFromCylindrical()` - transformation from `Cylindrical` type to `Spherical` type"
+"""
+    SphericalFromCylindrical()
+
+Transformation from `Cylindrical` type to `Spherical` type
+"""
 struct SphericalFromCylindrical <: Transformation; end
 
 Base.show(io::IO, trans::SphericalFromCartesian) = print(io, "SphericalFromCartesian()")

src/perspective.jl

@@ -13,10 +13,12 @@ This transformation is designed to be used in composition with other coordinate
 transformations, defining e.g. the position and orientation of the camera. For
 example:
 
-    cam_transform = PerspectiveMap() ∘ inv(AffineMap(cam_rotation, cam_position))
-    screen_points = map(cam_transform, points)
+```julia
+cam_transform = PerspectiveMap() ∘ inv(AffineMap(cam_rotation, cam_position))
+screen_points = map(cam_transform, points)
+```
 
-(see also `cameramap`)
+(see also [`cameramap`](@ref))
 """
 struct PerspectiveMap <: Transformation
 end
@@ -55,7 +57,7 @@ plane. For instance, you may wish to have the point (0,0) represent the top-left
 corner of your imaging sensor. This measurement is in the units after applying
 `scale` (e.g. pixels).
 
-(see also `PerspectiveMap`)
+(see also [`PerspectiveMap`](@ref))
 """
 cameramap() = PerspectiveMap()
 cameramap(scale::Number) =
@@ -66,4 +68,3 @@ cameramap(scale::Number, offset::Tuple{Number,Number}) =
     AffineMap(UniformScaling(scale), SVector(-offset[1], -offset[2])) ∘ PerspectiveMap()
 cameramap(scale::Tuple{Number, Number}, offset::Tuple{Number,Number}) =
     AffineMap(@SMatrix([scale[1] 0; 0 scale[2]]), SVector(-offset[1], -offset[2])) ∘ PerspectiveMap()
-