Merge pull request #316 from abhro/docstrings-patch-1

Fix docs and docstrings

docs/src/example/examples.md

@@ -1,7 +1,7 @@
 ```@meta
 DocTestSetup = quote
     using Luxor, Colors
-    end
+end
 ```
 # Simple examples
 
@@ -348,7 +348,7 @@ function drawmatrix(A::Matrix;
             halign=:center,
             valign=:middle)
         sethue("white")
-        box(table, r, c, action = :stroke)        
+        box(table, r, c, action = :stroke)
     end
 end
 

docs/src/explanation/basics.md

@@ -1,7 +1,7 @@
 ```@meta
 DocTestSetup = quote
     using Luxor, Colors
-    end
+end
 ```
 
 # The drawing model
@@ -27,7 +27,7 @@ usually `:path`, ie. add the graphics to the current path.
 The main Julia data types you'll encounter in Luxor are:
 
 | Name of type      | Purpose |
-| ---               | ---     |
+|:---               |:---     |
 | Drawing           | holds the current drawing |
 | Point             | specifies 2D points |
 | BoundingBox       | defines a bounding box |
@@ -74,68 +74,59 @@ svgimage # hide
 
 !!! note
 
-    Although this is the preferred coordinate system for most computer graphics software, including Luxor and Cairo, but mathematicians and scientists may well be used to the other convention, where the origin is in the center of the drawing and the y-axis increases up the page. See the macros such as [`@png`](@ref), [`@svg`](@ref), and [`@pdf`](@ref) which will put the origin at the center for you.
+    Although this is the preferred coordinate system for most computer graphics
+    software, including Luxor and Cairo, but mathematicians and scientists may
+    well be used to the other convention, where the origin is in the center of
+    the drawing and the y-axis increases up the page. See the macros such as
+    [`@png`](@ref), [`@svg`](@ref), and [`@pdf`](@ref) which will put the origin
+    at the center for you.
 
-You can reposition the origin at any time, using [`origin`](@ref). The 'user space' can be modified by functions such as [`scale`](@ref), [`translate`](@ref), and [`rotate`](@ref), or more directly using matrix transforms.
+You can reposition the origin at any time, using [`origin`](@ref). The 'user
+space' can be modified by functions such as [`scale`](@ref),
+[`translate`](@ref), and [`rotate`](@ref), or more directly using matrix
+transforms.
 
 The Point type holds two coordinates, `x` and `y`. For example:
 
-```julia-repl
-julia> P = Point(12.0, 13.0)
-Luxor.Point(12.0, 13.0)
-
-julia> P.x
-12.0
+```@setup points
+using Luxor
+```
 
-julia> P.y
-13.0
+```@repl points
+P = Point(12.0, 13.0)
+P.x
+P.y
 ```
 
-Points are immutable, so you can't change P's x or y values directly. But it's easy to make new points based on existing ones.
+Points are immutable, so you can't change `P`'s `x` or `y` values directly.
+But it's easy to make new points based on existing ones.
 
 Points can be added together:
 
-```julia-repl
-julia> Q = Point(4, 5)
-Luxor.Point(4.0, 5.0)
-
-julia> P + Q
-Luxor.Point(16.0, 18.0)
+```@repl points
+Q = Point(4, 5)
+P + Q
 ```
 
-You can add and multiply Points and scalars:
+You can multiply Points and scalars:
 
-```julia-repl
-julia> 10P
-Luxor.Point(120.0, 130.0)
-
-julia> P + 100
-Luxor.Point(112.0, 113.0)
+```@repl points
+10P
 ```
 
 You can also make new points by mixing Points and tuples:
 
-```julia-repl
-julia> P + (10, 0)
-Luxor.Point(22.0, 13.0)
-
-julia> Q * (0.5, 0.5)
-Luxor.Point(2.0, 2.5)
+```@repl points
+P + (10, 0)
+Q * (0.5, 0.5)
 ```
 
 You can also create points from tuples:
 
-```julia-repl
-julia> Point((1.0, 14))
-Point(1.0, 14.0)
-
-julia> plist = (1.0, 2.0), (-10, 10), (14.2, 15.4);
-
-julia> Point.(plist)
-3-element Array{Point,1}:
- Point(1.0, 2.0)
- Point(-10.0, 10.0)
- Point(14.2, 15.4)
+```@repl points
+Point((1.0, 14))
+plist = [(1.0, 2.0), (-10, 10), (14.2, 15.4)];
+Point.(plist)
 ```
 
 You can use the letter **O** as a shortcut to refer to the
@@ -294,8 +285,8 @@ s = svgstring()
 
 You can now examine the SVG elements in `s` programmatically:
 
-```julia
-eachmatch(r"rgb\(.*?\)", s) |> collect
+```julia-repl
+julia> eachmatch(r"rgb\(.*?\)", s) |> collect
 5-element Vector{RegexMatch}:
  RegexMatch("rgb(0%,0%,0%)")
  RegexMatch("rgb(79.6%,23.5%,20%)")

docs/src/explanation/fonts.md

@@ -1,7 +1,7 @@
 ```@meta
 DocTestSetup = quote
     using Luxor, Colors
-    end
+end
 ```
 
 # Fonts available on Linux CI systems
@@ -146,7 +146,8 @@ function drawfonts()
                     text(font, table[n])
                 end
                 @layer begin
-                    fface = replace(font, "Serif" => " Serif", 
+                    fface = replace(font,
+                        "Serif" => " Serif",
                         "Bold" => " Bold",
                         "Semibold" => " Semibold",
                         "Black" => " Black",
@@ -181,6 +182,7 @@ function drawfonts()
     end 1200 3400
     return d
 end
+nothing # hide
 ```
 
 ```@raw html

docs/src/explanation/imagematrix.md

@@ -2,14 +2,14 @@
 
 # Images as matrices
 
-While drawing a PNG drawing, you can at any time copy the current graphics in a drawing as a matrix of colored pixels, using the [`image_as_matrix`](@ref) function. 
+While drawing a PNG drawing, you can at any time copy the current graphics in a drawing as a matrix of colored pixels, using the [`image_as_matrix`](@ref) function.
 
 With the
 [`@imagematrix`](@ref) macro, you can create a drawing
 in the usual way, and then return the
 result as a matrix of colored pixels.
 
-This code draws a very small PNG image and also uses the `image_as_matrix()` function to stores the pixels in `mat` as a `25×25 reinterpret(ColorTypes.ARGB32, ::Matrix{UInt32}):`. 
+This code draws a very small PNG image and also uses the `image_as_matrix()` function to stores the pixels in `mat` as a `25×25 reinterpret(ColorTypes.ARGB32, ::Matrix{UInt32}):`.
 
 ```julia
 using Luxor

docs/src/explanation/pathspolygons.md

@@ -20,7 +20,9 @@ and the current graphics state (color, line thickness, and
 so on), in response to the functions you call.
 
 When called, the following function creates a single path consisting of three separate
-shapes - a line, a rectangular box, and a circle. The [`move()`](@ref) function as used here is essentially a "pick up the pen and move it elsewhere" instruction. [`line()`](@ref) adds a straight line segment to the current path.
+shapes - a line, a rectangular box, and a circle. The [`move()`](@ref) function
+as used here is essentially a "pick up the pen and move it elsewhere"
+instruction. [`line()`](@ref) adds a straight line segment to the current path.
 The `circle()` function adds four Bézier curves that provide a good approximation to a circle.
 
 ```julia
@@ -69,24 +71,23 @@ d = @drawsvg begin
     # rule.(between.(O - (250, 0), O + (250, 0), 0:0.01:1), -π/3)
     # Luxor >= "v4.0"
     rule.(between(O - (250, 0), O + (250, 0), 0:0.01:1), -π/3)
-    end 800 500
+end 800 500
 ```
 
 ```@example pathexample
 d # hide
 ```
 
 When you run this function, the path is added to the drawing.
-The top path, in purple, is drawn when
-[`strokepath()`](@ref) is called. Each of the
-three shapes is stroked with the same current settings
+The top path, in purple, is drawn when [`strokepath()`](@ref) is called.
+Each of the three shapes is stroked with the same current settings
 (color, line thickness, dash pattern, and so on).
 
 After calling the function again, the middle row shows the effect of calling
 [`fillpath()`](@ref) on the new path. It fills each of
 the three shapes in the path with orange.
 
-Finally, after calling the function again, 
+Finally, after calling the function again,
 the [`clip()`](@ref) function turns this new path into a clipping path. The
 [`rule()`](@ref) function draws green ruled lines, which are
 clipped by the outlines of the shapes in the path.
@@ -100,7 +101,7 @@ Many functions in Luxor have an `action` keyword argument or
 parameter. If you want to add that shape to the current
 path, use `:path`. If you want to both add the shape _and_
 finish and draw the current path, use one of `stroke`,
-`fill`, etc.  
+`fill`, etc.
 
 After the path is stroked or filled, it's emptied out, ready
 for you to start over again. There's always a current path. But you can also use one of the
@@ -113,7 +114,6 @@ also convert the path to a clipping path using
 As you can see, a single path can contain multiple separate graphic shapes.
 
 ### Holes
-beetween
 If you want a path to contain holes,
 you add the hole shapes to the current path after reversing
 their direction. For example, to put a square hole inside a

docs/src/explanation/strokepathdispatch.md

@@ -1,4 +1,4 @@
-# Custom behavior for strokepath and fillpath 
+# Custom behavior for strokepath and fillpath
 
 There are four functions that "paint" the current path to the drawing:
 they are `strokepath` , `strokepreserve` , `fillpath`, and `fillpreserve`.
@@ -7,24 +7,24 @@ Other mechanisms to draw on the canvas are `clip` , `clippreserve` and `paint`.
 
 If you would like to have some custom behavior for these functions, such as adding a way to extract or modify paths etc.), Luxor provides a way to do so.
 
-These four functions are basically defined as: 
+These four functions are basically defined as:
 
 `funcname() = funcname(DISPATCHER[1])`
 `funcname(::DefaultLuxor) = {...do_some_graphics_work...}`
 `funcname(::LDispatcher) = funcname(DefaultLuxor())`
 
-`DISPATCHER[1]` is defined as an instance of a struct (with no fields) 
+`DISPATCHER[1]` is defined as an instance of a struct (with no fields)
 `DefaultLuxor`. The datatype `DefaultLuxor` is a subtype of `LDispatcher`.
 `DISPATCHER` as such is defined as an array of `LDispatcher`. This is to make
-it mutable. Only the first element ie. `DISPATCHER[1]` is ever used. 
+it mutable. Only the first element ie. `DISPATCHER[1]` is ever used.
 
 You can make custom behavior for the functions in the following way:
 
-1 Define a new struct `MyDispatcher <: Luxor.LDispatcher` (it needn't have any fields).
+1. Define a new struct `MyDispatcher <: Luxor.LDispatcher` (it needn't have any fields).
 
-2 Define a function that dispatches on the above struct.
+2. Define a function that dispatches on the above struct.
 
-3 Change `Luxor.DISPATCHER[1]` to an instance of your struct. 
+3. Change `Luxor.DISPATCHER[1]` to an instance of your struct.
 
 Here's an example of a method that changes the behavior of all calls
 to `strokepath()` such that the current color is printed to the terminal as the path is drawn.
@@ -33,7 +33,7 @@ to `strokepath()` such that the current color is printed to the terminal as the
 struct MyDispatcher <: Luxor.LDispatcher end
 function Luxor.strokepath(::MyDispatcher)
     println("$(Luxor.get_current_color())")
-	return Luxor.strokepath(Luxor.DefaultLuxor())
+    return Luxor.strokepath(Luxor.DefaultLuxor())
 end
 Luxor.DISPATCHER[1] = MyDispatcher()
 
@@ -46,11 +46,11 @@ end
 ```
 
 Now, all calls to `strokepath()` whether explicitly called or through other
-functions (for example, with the :stroke action) will print the current color 
+functions (for example, with the :stroke action) will print the current color
 just before the path is stroked.
 
 Similar dispatches can be written for `strokepreserve`, `fillpath`,
-`fillpreserve`, `clip`, `clippreserve`, and `paint`. 
+`fillpreserve`, `clip`, `clippreserve`, and `paint`.
 
 Functions which don't have methods defined for the types will default
 to calling `funcname(Luxor.DefaultLuxor())`

docs/src/explanation/transforms.md

@@ -1,12 +1,12 @@
 ```@meta
 DocTestSetup = quote
     using Luxor, Colors
-    end
+end
 ```
 
-Graphics are placed on the current drawing according to the *current transformation matrix*. You can either modify this indirectly, using functions, or set the matrix directly.
+# Transforms and matrices
 
-# Transformation functions
+Graphics are placed on the current drawing according to the *current transformation matrix*. You can either modify this indirectly, using functions, or set the matrix directly.
 
 For basic transformations, use [`translate(tx, ty)`](@ref), [`scale(sx, sy)`](@ref), and [`rotate(a)`](@ref).
 
@@ -102,8 +102,8 @@ another pair of low and high values.
 using Luxor
 
 reddot(pos) = @layer begin
-sethue("red")
-circle(pos, 8, :fill)
+    sethue("red")
+    circle(pos, 8, :fill)
 end
 
 diagram = @drawsvg begin
@@ -123,12 +123,12 @@ diagram = @drawsvg begin
 
     tickline(pts...,
         startnumber = 1,
-        finishnumber = 2,        
+        finishnumber = 2,
         minor=0,
         major=9)
     tickline(pts...,
         startnumber = 30,
-        finishnumber = 40,        
+        finishnumber = 40,
         minor=0,
         major=9,
         major_tick_function = (n, pos; startnumber=30, finishnumber=40, nticks=10) -> begin
@@ -178,13 +178,13 @@ and Luxor/Cairo matrix functions accept and return simple 6-element vectors:
 
 ```julia-repl
 julia> getmatrix()
-6-element Array{Float64,1}:
-   1.0
-   0.0
-   0.0
-   1.0
-   0.0
-   0.0
+6-element Vector{Float64}:
+ 1.0
+ 0.0
+ 0.0
+ 1.0
+ 0.0
+ 0.0
 ```
 
 !!! note
@@ -283,7 +283,7 @@ diagram = @drawsvg begin
     end
 
     @layer begin
-        translate(table[2])        
+        translate(table[2])
         text("computing: y downwards", O  + (0, 100), halign=:center)
         rulers()
     end
@@ -312,7 +312,7 @@ using Luxor # hide
 
     @layer begin
         translate(table[2])
-        transform([1 0 0 -1 0 0])               # <--
+        transform([1 0 0 -1 0 0])           # <--
         arrow(pts...)
         rulers()
     end