Merge pull request #131 from aviatesk/updates

fix some doc syntax and add some references

Author: MikeInnes

docs/Manifest.toml

@@ -3,12 +3,6 @@
 [[Base64]]
 uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 
-[[DataStructures]]
-deps = ["InteractiveUtils", "OrderedCollections"]
-git-tree-sha1 = "1fe8fad5fc84686dcbc674aa255bc867a64f8132"
-uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
-version = "0.17.5"
-
 [[Dates]]
 deps = ["Printf"]
 uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -24,10 +18,10 @@ uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 version = "0.8.1"
 
 [[Documenter]]
-deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
-git-tree-sha1 = "04d40966cddd2ea5d227e7130484b57ac4718596"
+deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "646ebc3db49889ffeb4c36f89e5d82c6a26295ff"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.22.1"
+version = "0.24.7"
 
 [[InteractiveUtils]]
 deps = ["Markdown"]
@@ -40,6 +34,7 @@ uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 version = "0.21.0"
 
 [[LibGit2]]
+deps = ["Printf"]
 uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
 
 [[Libdl]]
@@ -49,10 +44,10 @@ uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
 
 [[MacroTools]]
-deps = ["DataStructures", "Markdown", "Random", "Test"]
+deps = ["Markdown", "Random"]
 path = ".."
 uuid = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
-version = "0.5.2"
+version = "0.5.5"
 
 [[Markdown]]
 deps = ["Base64"]
@@ -61,17 +56,11 @@ uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
 [[Mmap]]
 uuid = "a63ad114-7e13-5084-954f-fe012c677804"
 
-[[OrderedCollections]]
-deps = ["Random", "Serialization", "Test"]
-git-tree-sha1 = "c4c13474d23c60d20a67b217f1d7f22a40edf8f1"
-uuid = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
-version = "1.1.0"
-
 [[Parsers]]
 deps = ["Dates", "Test"]
-git-tree-sha1 = "a23968e107c0544aca91bfab6f7dd34de1206a54"
+git-tree-sha1 = "0c16b3179190d3046c073440d94172cfc3bb0553"
 uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
-version = "0.3.9"
+version = "0.3.12"
 
 [[Pkg]]
 deps = ["Dates", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]

docs/make.jl

@@ -9,4 +9,5 @@ makedocs(
     format = Documenter.HTML(prettyurls = haskey(ENV, "CI")))
 
 deploydocs(
-  repo = "github.com/MikeInnes/MacroTools.jl.git",)
+  repo = "github.com/MikeInnes/MacroTools.jl.git",
+  push_preview = true)

docs/src/utilities.md

@@ -56,7 +56,7 @@ such as `x::Int=2` and returns `(arg_name, arg_type, slurp, default)`. `default`
 `nothing` when there is none. For example:
 
 ```julia
-> map(splitarg, (:(f(y, a=2, x::Int=nothing, args...))).args[2:end])
+julia> map(splitarg, (:(f(y, a=2, x::Int=nothing, args...))).args[2:end])
 4-element Array{Tuple{Symbol,Symbol,Bool,Any},1}:
  (:y, :Any, false, nothing)  
  (:a, :Any, false, 2)        
@@ -67,6 +67,7 @@ such as `x::Int=2` and returns `(arg_name, arg_type, slurp, default)`. `default`
 ## Other Utilities
 
 ```@docs
+MacroTools.@q
 MacroTools.isexpr
 MacroTools.rmlines
 MacroTools.unblock

src/examples/threading.jl

@@ -1,18 +1,22 @@
 """
 The threading macro is like a more flexible version of the `|>` operator.
 
-    @> x f = f(x)
-    @> x g f == f(g(x))
-    @> x a b c d e == e(d(c(b(a(x)))))
+```julia
+@> x f = f(x)
+@> x g f == f(g(x))
+@> x a b c d e == e(d(c(b(a(x)))))
+```
 
-Unlike |>, functions can have arguments - the value
+Unlike `|>`, functions can have arguments - the value
 preceding a function will be treated as its first argument
 
-    @> x g(y, z) f == f(g(x, y, z))
+```julia
+@> x g(y, z) f == f(g(x, y, z))
 
-    @> x g f(y, z) == f(g(x), y, z)
+@> x g f(y, z) == f(g(x), y, z)
+```
 
-See also `@>>`, `@as`.
+See also [`@>>`](@ref), [`@as`](@ref).
 """
 macro >(exs...)
   thread(x) = isexpr(x, :block) ? thread(rmlines(x).args...) : x
@@ -28,11 +32,13 @@ macro >(exs...)
 end
 
 """
-Same as `@>`, but threads the last argument.
+Same as [`@>`](@ref), but threads the last argument.
 
-  @>> x g(y, z) f == f(g(y, z, x))
+```julia
+@>> x g(y, z) f == f(g(y, z, x))
 
-  @>> x g f(y, z) == f(y, z, g(x))
+@>> x g f(y, z) == f(y, z, g(x))
+```
 """
 macro >>(exs...)
   thread(x) = isexpr(x, :block) ? thread(rmlines(x).args...) : x

src/utils.jl

@@ -11,10 +11,11 @@ assoc!(d, k, v) = (d[k] = v; d)
 """
     @esc x y
 
-is the same as
-
-    x = esc(x)
-    y = esc(y)
+is the same as:
+```julia
+x = esc(x)
+y = esc(y)
+```
 """
 macro esc(xs...)
   :($([:($x = esc($x)) for x in map(esc, xs)]...);)
@@ -26,6 +27,8 @@ end
 Like the `quote` keyword but doesn't insert line numbers from the construction
 site. e.g. compare `@q begin end` with `quote end`. Line numbers of interpolated
 expressions are preserverd.
+
+See also: [`rmlines`](@ref)
 """
 macro q(ex)
   Expr(:quote, striplines(ex))
@@ -65,6 +68,8 @@ To work with nested blocks:
 ```julia
 prewalk(rmlines, ex)
 ```
+
+See also: [`@q`](@ref)
 """
 rmlines(x) = x
 function rmlines(x::Expr)
@@ -108,8 +113,9 @@ walk(x::Expr, inner, outer) = outer(Expr(x.head, map(inner, x.args)...))
     postwalk(f, expr)
 
 Applies `f` to each node in the given expression tree, returning the result.
-`f` sees expressions *after* they have been transformed by the walk. See also
-`prewalk`.
+`f` sees expressions *after* they have been transformed by the walk.
+
+See also: [`prewalk`](@ref).
 """
 postwalk(f, x) = walk(x, x -> postwalk(f, x), f)
 
@@ -121,7 +127,7 @@ Applies `f` to each node in the given expression tree, returning the result.
 walk will be applied to whatever `f` returns.
 
 This makes `prewalk` somewhat prone to infinite loops; you probably want to try
-`postwalk` first.
+[`postwalk`](@ref) first.
 """
 prewalk(f, x)  = walk(f(x), x -> prewalk(f, x), identity)
 
@@ -133,7 +139,9 @@ replace(ex, s, s′) = prewalk(x -> x == s ? s′ : x, ex)
 Simple expression match; will return `true` if the expression `x` can be found
 inside `expr`.
 
-    inexpr(:(2+2), 2) == true
+```julia
+inexpr(:(2+2), 2) == true
+```
 """
 function inexpr(ex, x)
   result = false
@@ -162,11 +170,13 @@ end
 
 Replaces gensyms with unique ids (deterministically).
 
-    julia> x, y = gensym("x"), gensym("y")
-    (Symbol("##x#363"), Symbol("##y#364"))
+```julia
+julia> x, y = gensym("x"), gensym("y")
+(Symbol("##x#363"), Symbol("##y#364"))
 
-    julia> MacroTools.gensym_ids(:(\$x+\$y))
-    :(x_1 + y_2)
+julia> MacroTools.gensym_ids(:(\$x+\$y))
+:(x_1 + y_2)
+```
 """
 function gensym_ids(ex)
   counter = 0
@@ -184,11 +194,13 @@ end
 Replaces gensyms with animal names.
 This makes gensym'd code far easier to follow.
 
-    julia> x, y = gensym("x"), gensym("y")
-    (Symbol("##x#363"), Symbol("##y#364"))
+```julia
+julia> x, y = gensym("x"), gensym("y")
+(Symbol("##x#363"), Symbol("##y#364"))
 
-    julia> MacroTools.alias_gensyms(:(\$x+\$y))
-    :(porcupine + gull)
+julia> MacroTools.alias_gensyms(:(\$x+\$y))
+:(porcupine + gull)
+```
 """
 function alias_gensyms(ex)
   left = copy(animals)
@@ -201,7 +213,9 @@ end
 """
 More convenient macro expansion, e.g.
 
-    @expand @time foo()
+```julia
+@expand @time foo()
+```
 """
 @static if VERSION <= v"0.7.0-DEV.484"
   macro expand(ex)
@@ -248,7 +262,10 @@ function shortdef1(ex)
 end
 shortdef(ex) = prewalk(shortdef1, ex)
 
-""" `gatherwheres(:(f(x::T, y::U) where T where U)) => (:(f(x::T, y::U)), (:U, :T))`
+"""
+```julia
+gatherwheres(:(f(x::T, y::U) where T where U)) == (:(f(x::T, y::U)), (:U, :T))
+```
 """
 function gatherwheres(ex)
   if @capture(ex, (f_ where {params1__}))
@@ -272,14 +289,16 @@ end
 and return `Dict(:name=>..., :args=>..., etc.)`. The definition can be rebuilt by
 calling `MacroTools.combinedef(dict)`, or explicitly with
 
-```
+```julia
 rtype = get(dict, :rtype, :Any)
 all_params = [get(dict, :params, [])..., get(dict, :whereparams, [])...]
 :(function \$(dict[:name]){\$(all_params...)}(\$(dict[:args]...);
                                             \$(dict[:kwargs]...))::\$rtype
       \$(dict[:body])
   end)
 ```
+
+See also: [`combinedef`](@ref)
 """
 function splitdef(fdef)
   error_msg = "Not a function definition: $(repr(fdef))"
@@ -321,8 +340,9 @@ end
 """
     combinedef(dict::Dict)
 
-`combinedef` is the inverse of `splitdef`. It takes a splitdef-like Dict
-and returns a function definition. """
+`combinedef` is the inverse of [`splitdef`](@ref). It takes a `splitdef`-like Dict
+and returns a function definition.
+"""
 function combinedef(dict::Dict)
   rtype = get(dict, :rtype, nothing)
   params = get(dict, :params, [])
@@ -383,7 +403,8 @@ end
 """
     combinearg(arg_name, arg_type, is_splat, default)
 
-`combinearg` is the inverse of `splitarg`. """
+`combinearg` is the inverse of [`splitarg`](@ref).
+"""
 function combinearg(arg_name, arg_type, is_splat, default)
     a = arg_name===nothing ? :(::$arg_type) : :($arg_name::$arg_type)
     a2 = is_splat ? Expr(:..., a) : a
@@ -405,13 +426,15 @@ Match function arguments (whether from a definition or a function call) such as
 `default` are `nothing` when they are absent. For example:
 
 ```julia
-> map(splitarg, (:(f(a=2, x::Int=nothing, y, args...))).args[2:end])
+julia> map(splitarg, (:(f(a=2, x::Int=nothing, y, args...))).args[2:end])
 4-element Array{Tuple{Symbol,Symbol,Bool,Any},1}:
  (:a, :Any, false, 2)
  (:x, :Int, false, :nothing)
  (:y, :Any, false, nothing)
  (:args, :Any, true, nothing)
 ```
+
+See also: [`combinearg`](@ref)
 """
 function splitarg(arg_expr)
     splitvar(arg) =