Enable doctests the the manual

Switching to julia-repl revealed several code blocks that could
trivially be turned into doctests.

doc/src/devdocs/cartesian.md

@@ -53,9 +53,19 @@ is `@nref 3 A i` (as in `A[i_1,i_2,i_3]`, where the array comes first).
 If you're developing code with Cartesian, you may find that debugging is easier when you examine
 the generated code, using `macroexpand`:
 
-```julia-repl
+```@meta
+DocTestSetup = quote
+    import Base.Cartesian: @nref
+end
+```
+
+```jldoctest
 julia> macroexpand(:(@nref 2 A i))
-:(A[i_1,i_2])
+:(A[i_1, i_2])
+```
+
+```@meta
+DocTestSetup = nothing
 ```
 
 ### Supplying the number of expressions

doc/src/devdocs/reflection.md

@@ -14,7 +14,7 @@ The names of `DataType` fields may be interrogated using [`fieldnames()`](@ref).
 given the following type, `fieldnames(Point)` returns an arrays of [`Symbol`](@ref) elements representing
 the field names:
 
-```julia-repl
+```jldoctest struct_point
 julia> struct Point
            x::Int
            y
@@ -29,17 +29,17 @@ julia> fieldnames(Point)
 The type of each field in a `Point` object is stored in the `types` field of the `Point` variable
 itself:
 
-```julia-repl
+```jldoctest struct_point
 julia> Point.types
-svec(Int64,Any)
+svec(Int64, Any)
 ```
 
 While `x` is annotated as an `Int`, `y` was unannotated in the type definition, therefore `y`
 defaults to the `Any` type.
 
 Types are themselves represented as a structure called `DataType`:
 
-```julia-repl
+```jldoctest struct_point
 julia> typeof(Point)
 DataType
 ```
@@ -52,9 +52,9 @@ of these fields is the `types` field observed in the example above.
 The *direct* subtypes of any `DataType` may be listed using [`subtypes()`](@ref). For example,
 the abstract `DataType``AbstractFloat` has four (concrete) subtypes:
 
-```julia-repl
+```jldoctest
 julia> subtypes(AbstractFloat)
-4-element Array{DataType,1}:
+4-element Array{Union{DataType, UnionAll},1}:
  BigFloat
  Float16
  Float32
@@ -83,9 +83,9 @@ the unquoted and interpolated expression (`Expr`) form for a given macro. To use
 `quote` the expression block itself (otherwise, the macro will be evaluated and the result will
 be passed instead!). For example:
 
-```julia-repl
+```jldoctest
 julia> macroexpand( :(@edit println("")) )
-:((Base.edit)(println,(Base.typesof)("")))
+:((Base.edit)(println, (Base.typesof)("")))
 ```
 
 The functions `Base.Meta.show_sexpr()` and [`dump()`](@ref) are used to display S-expr style views
@@ -95,11 +95,11 @@ Finally, the [`expand()`](@ref) function gives the `lowered` form of any express
 particular interest for understanding both macros and top-level statements such as function declarations
 and variable assignments:
 
-```julia-repl
+```jldoctest
 julia> expand( :(f() = 1) )
 :(begin
         $(Expr(:method, :f))
-        $(Expr(:method, :f, :((Core.svec)((Core.svec)((Core.Typeof)(f)),(Core.svec)())), CodeInfo(:(begin  # none, line 1:
+        $(Expr(:method, :f, :((Core.svec)((Core.svec)((Core.Typeof)(f)), (Core.svec)())), CodeInfo(:(begin  # none, line 1:
         return 1
     end)), false))
         return f

doc/src/devdocs/subarrays.md

@@ -152,7 +152,7 @@ we can define dispatch directly on `SubArray{T,N,A,I,true}` without any intermed
 Since this computation doesn't depend on runtime values, it can miss some cases in which the stride
 happens to be uniform:
 
-```julia-repl
+```jldoctest
 julia> A = reshape(1:4*2, 4, 2)
 4×2 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
  1  5
@@ -171,7 +171,7 @@ A view constructed as `view(A, 2:2:4, :)` happens to have uniform stride, and th
 indexing indeed could be performed efficiently.  However, success in this case depends on the
 size of the array: if the first dimension instead were odd,
 
-```julia-repl
+```jldoctest
 julia> A = reshape(1:5*2, 5, 2)
 5×2 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
  1   6

doc/src/manual/arrays.md

@@ -768,7 +768,7 @@ The [`sparse()`](@ref) function is often a handy way to construct sparse matrice
 its input a vector `I` of row indices, a vector `J` of column indices, and a vector `V` of nonzero
 values. `sparse(I,J,V)` constructs a sparse matrix such that `S[I[k], J[k]] = V[k]`.
 
-```julia-repl
+```jldoctest sparse_function
 julia> I = [1, 4, 3, 5]; J = [4, 7, 18, 9]; V = [1, 2, -5, 3];
 
 julia> S = sparse(I,J,V)
@@ -782,12 +782,12 @@ julia> S = sparse(I,J,V)
 The inverse of the [`sparse()`](@ref) function is [`findn()`](@ref), which retrieves the inputs
 used to create the sparse matrix.
 
-```julia-repl
+```jldoctest sparse_function
 julia> findn(S)
-([1,4,5,3],[4,7,9,18])
+([1, 4, 5, 3], [4, 7, 9, 18])
 
 julia> findnz(S)
-([1,4,5,3],[4,7,9,18],[1,2,3,-5])
+([1, 4, 5, 3], [4, 7, 9, 18], [1, 2, 3, -5])
 ```
 
 Another way to create sparse matrices is to convert a dense matrix into a sparse matrix using

doc/src/manual/conversion-and-promotion.md

@@ -46,7 +46,7 @@ generally takes two arguments: the first is a type object while the second is a
 to that type; the returned value is the value converted to an instance of given type. The simplest
 way to understand this function is to see it in action:
 
-```julia-repl
+```jldoctest
 julia> x = 12
 12
 
@@ -66,25 +66,24 @@ julia> typeof(ans)
 Float64
 
 julia> a = Any[1 2 3; 4 5 6]
-2x3 Array{Any,2}:
+2×3 Array{Any,2}:
  1  2  3
  4  5  6
 
 julia> convert(Array{Float64}, a)
-2x3 Array{Float64,2}:
+2×3 Array{Float64,2}:
  1.0  2.0  3.0
  4.0  5.0  6.0
 ```
 
 Conversion isn't always possible, in which case a no method error is thrown indicating that `convert`
 doesn't know how to perform the requested conversion:
 
-```julia-repl
+```jldoctest
 julia> convert(AbstractFloat, "foo")
 ERROR: MethodError: Cannot `convert` an object of type String to an object of type AbstractFloat
 This may have arisen from a call to the constructor AbstractFloat(...),
 since type constructors fall back to convert methods.
- ...
 ```
 
 Some languages consider parsing strings as numbers or formatting numbers as strings to be conversions
@@ -111,7 +110,7 @@ example, since the type is a singleton, there would never be any reason to use i
 the body. When invoked, the method determines whether a numeric value is true or false as a boolean,
 by comparing it to one and zero:
 
-```julia-repl
+```jldoctest
 julia> convert(Bool, 1)
 true
 
@@ -196,24 +195,24 @@ any number of arguments, and returns a tuple of the same number of values, conve
 type, or throws an exception if promotion is not possible. The most common use case for promotion
 is to convert numeric arguments to a common type:
 
-```julia-repl
+```jldoctest
 julia> promote(1, 2.5)
-(1.0,2.5)
+(1.0, 2.5)
 
 julia> promote(1, 2.5, 3)
-(1.0,2.5,3.0)
+(1.0, 2.5, 3.0)
 
 julia> promote(2, 3//4)
-(2//1,3//4)
+(2//1, 3//4)
 
 julia> promote(1, 2.5, 3, 3//4)
-(1.0,2.5,3.0,0.75)
+(1.0, 2.5, 3.0, 0.75)
 
 julia> promote(1.5, im)
-(1.5 + 0.0im,0.0 + 1.0im)
+(1.5 + 0.0im, 0.0 + 1.0im)
 
 julia> promote(1 + 2im, 3//4)
-(1//1 + 2//1*im,3//4 + 0//1*im)
+(1//1 + 2//1*im, 3//4 + 0//1*im)
 ```
 
 Floating-point values are promoted to the largest of the floating-point argument types. Integer
@@ -253,7 +252,7 @@ Rational(n::Integer, d::Integer) = Rational(promote(n,d)...)
 
 This allows calls like the following to work:
 
-```julia-repl
+```jldoctest
 julia> Rational(Int8(15),Int32(-5))
 -3//1
 
@@ -297,7 +296,7 @@ which, given any number of type objects, returns the common type to which those
 to `promote` should be promoted. Thus, if one wants to know, in absence of actual values, what
 type a collection of values of certain types would promote to, one can use `promote_type`:
 
-```julia-repl
+```jldoctest
 julia> promote_type(Int8, UInt16)
 Int64
 ```

doc/src/manual/integers-and-floating-point-numbers.md

@@ -584,7 +584,7 @@ To make common numeric formulas and expressions clearer, Julia allows variables
 preceded by a numeric literal, implying multiplication. This makes writing polynomial expressions
 much cleaner:
 
-```jldoctest
+```jldoctest numeric-coefficients
 julia> x = 3
 3
 
@@ -597,7 +597,7 @@ julia> 1.5x^2 - .5x + 1
 
 It also makes writing exponential functions more elegant:
 
-```julia-repl
+```jldoctest numeric-coefficients
 julia> 2^2x
 64
 ```
@@ -607,23 +607,23 @@ negation. So `2^3x` is parsed as `2^(3x)`, and `2x^3` is parsed as `2*(x^3)`.
 
 Numeric literals also work as coefficients to parenthesized expressions:
 
-```julia-repl
+```jldoctest numeric-coefficients
 julia> 2(x-1)^2 - 3(x-1) + 1
 3
 ```
 
 Additionally, parenthesized expressions can be used as coefficients to variables, implying multiplication
 of the expression by the variable:
 
-```julia-repl
+```jldoctest numeric-coefficients
 julia> (x-1)x
 6
 ```
 
 Neither juxtaposition of two parenthesized expressions, nor placing a variable before a parenthesized
 expression, however, can be used to imply multiplication:
 
-```julia-repl
+```jldoctest numeric-coefficients
 julia> (x-1)(x+1)
 ERROR: MethodError: objects of type Int64 are not callable
 

doc/src/manual/metaprogramming.md

@@ -920,7 +920,7 @@ we returned from the definition, now with the *value* of `x`.
 
 What happens if we evaluate `foo` again with a type that we have already used?
 
-```julia-repl generated
+```jldoctest generated
 julia> foo(4)
 16
 ```

doc/src/manual/performance-tips.md

@@ -257,7 +257,7 @@ like `m` but not for objects like `t`.
 Of course, all of this is true only if we construct `m` with a concrete type.  We can break this
 by explicitly constructing it with an abstract type:
 
-```julia-repl myambig2
+```jldoctest myambig2
 julia> m = MyType{AbstractFloat}(3.2)
 MyType{AbstractFloat}(3.2)
 
@@ -429,7 +429,7 @@ the array type `A`.
 However, there's one remaining hole: we haven't enforced that `A` has element type `T`, so it's
 perfectly possible to construct an object like this:
 
-```julia-repl
+```jldoctest containers2
 julia> b = MyContainer{Int64, UnitRange{Float64}}(UnitRange(1.3, 5.0));
 
 julia> typeof(b)

doc/src/manual/running-external-programs.md

@@ -49,7 +49,7 @@ true
 
 More generally, you can use [`open()`](@ref) to read from or write to an external command.
 
-```julia-repl
+```jldoctest
 julia> open(`less`, "w", STDOUT) do io
            for i = 1:3
                println(io, i)

doc/src/manual/strings.md

@@ -645,7 +645,7 @@ For when a capture doesn't match, instead of a substring, `m.captures` contains
 position, and `m.offsets` has a zero offset (recall that indices in Julia are 1-based, so a zero
 offset into a string is invalid). Here is a pair of somewhat contrived examples:
 
-```jldoctest
+```jldoctest acdmatch
 julia> m = match(r"(a|b)(c)?(d)", "acd")
 RegexMatch("acd", 1="a", 2="c", 3="d")
 
@@ -692,7 +692,7 @@ julia> m.offsets
 It is convenient to have captures returned as an array so that one can use destructuring syntax
 to bind them to local variables:
 
-```julia-repl
+```jldoctest acdmatch
 julia> first, second, third = m.captures; first
 "a"
 ```

doc/src/manual/variables-and-scoping.md

@@ -174,7 +174,7 @@ julia> x
 Within soft scopes, the *global* keyword is never necessary, although allowed. The only case
 when it would change the semantics is (currently) a syntax error:
 
-```julia-repl
+```jldoctest
 julia> let
            local j = 2
            let
@@ -332,7 +332,7 @@ The reason to allow *modifying local* variables of parent scopes in nested funct
 constructing [closures](https://en.wikipedia.org/wiki/Closure_%28computer_programming%29) which
 have a private state, for instance the `state` variable in the following example:
 
-```julia-repl
+```jldoctest
 julia> let
            state = 0
            global counter
@@ -411,7 +411,7 @@ julia> Fs[2]()
 Since the `begin` construct does not introduce a new scope, it can be useful to use a zero-argument
 `let` to just introduce a new scope block without creating any new bindings:
 
-```julia-repl
+```jldoctest
 julia> let
            local x = 1
            let

doc/src/stdlib/sort.md

@@ -3,7 +3,7 @@
 Julia has an extensive, flexible API for sorting and interacting with already-sorted arrays of
 values. By default, Julia picks reasonable algorithms and sorts in standard ascending order:
 
-```julia-repl
+```jldoctest
 julia> sort([2,3,1])
 3-element Array{Int64,1}:
  1
@@ -13,7 +13,7 @@ julia> sort([2,3,1])
 
 You can easily sort in reverse order as well:
 
-```julia-repl
+```jldoctest
 julia> sort([2,3,1], rev=true)
 3-element Array{Int64,1}:
  3
@@ -23,7 +23,7 @@ julia> sort([2,3,1], rev=true)
 
 To sort an array in-place, use the "bang" version of the sort function:
 
-```julia-repl
+```jldoctest
 julia> a = [2,3,1];
 
 julia> sort!(a);