docs: turn doctests into @example blocks

Author: AayushSabharwal

docs/src/manual/rewrite.md

@@ -8,7 +8,7 @@ Rewrite rules match and transform an expression. A rule is written using either
 
 Here is a simple rewrite rule, that uses formula for the double angle of the sine function:
 
-```jldoctest rewrite
+```@example rewrite
 using SymbolicUtils
 
 @syms w z α::Real β::Real
@@ -18,9 +18,6 @@ using SymbolicUtils
 r1 = @rule sin(2(~x)) => 2sin(~x)*cos(~x)
 
 r1(sin(2z))
-
-# output
-2cos(z)*sin(z)
 ```
 
 The `@rule` macro takes a pair of patterns -- the _matcher_ and the _consequent_ (`@rule matcher => consequent`). If an expression matches the matcher pattern, it is rewritten to the consequent pattern. `@rule` returns a callable object that applies the rule to an expression.
@@ -30,47 +27,32 @@ The `@rule` macro takes a pair of patterns -- the _matcher_ and the _consequent_
 If you try to apply this rule to an expression with triple angle, it will return `nothing` -- this is the way a rule signifies failure to match.
 ```julia
 r1(sin(3z))
-
-# output
-nothing
 ```
 
 Slot variable (matcher) is not necessary a single variable:
-```jldoctest rewrite
+```@example rewrite
 r1(sin(2*(w-z)))
-
-# output
-2sin(w - z)*cos(w - z)
 ```
 
 And can also match a function:
 ```julia
 r = @rule (~f)(z+1) => ~f
 
 r(sin(z+1))
-
-# output
-sin (generic function with 20 methods)
-
 ```
 Rules are of course not limited to single slot variable
 
-```jldoctest rewrite
+```@example rewrite
 r2 = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y);
 
 r2(sin(α+β))
-
-# output
-cos(β)*sin(α) + sin(β)*cos(α)
 ```
 
 Now let's say you want to catch the coefficients of a second degree polynomial in z. You can do that with:
-```jldoctest rewrite
+```@example rewrite
 c2d = @rule ~a + ~b*z + ~c*z^2 => (~a, ~b, ~c)
 
-c2d(3 + 2z + 5z^2)
-# output
-(3, 2, 5)
+2d(3 + 2z + 5z^2)
 ```
 Great! But if you try:
 ```julia
@@ -80,12 +62,10 @@ c2d(3 + 2z + z^2)
 nothing
 ```
 the rule is not applied. This is because in the input polynomial there isn't a multiplication in front of the `z^2`. For this you can use **defslot variables**, with syntax `~!a`:
-```jldoctest rewrite
+```@example rewrite
 c2d = @rule ~!a + ~!b*z + ~!c*z^2 => (~a, ~b, ~c)
 
-c2d(3 + 2z + z^2)
-# output
-(3, 2, 1)
+2d(3 + 2z + z^2)
 ```
 They work like normal slot variables, but if they are not present they take a default value depending on the operation they are in, in the above example `~b = 1`. Currently defslot variables can be defined in:
 
@@ -97,52 +77,31 @@ addition `+` | 0
 
 If you want to match a variable number of subexpressions at once, you will need a **segment variable**. `~~xs` in the following example is a segment variable:
 
-```jldoctest rewrite
+```@example rewrite
 @syms x y z
 @rule(+(~~xs) => ~~xs)(x + y + z)
-
-# output
-3-element view(::ReadOnlyArrays.ReadOnlyVector{Any, SymbolicUtils.SmallVec{Any, Vector{Any}}}, 1:3) with eltype Any:
- x
- y
- z
 ```
 
 `~~xs` is a vector of subexpressions matched. You can use it to construct something more useful:
 
-```jldoctest rewrite
+```@example rewrite
 r3 = @rule ~x * +(~~ys) => sum(map(y-> ~x * y, ~~ys));
 
 r3(2 * (w+w+α+β))
-
-# output
-4w + 2α + 2β
 ```
 
 Notice that the expression was autosimplified before application of the rule.
 
-```jldoctest rewrite
+```@example rewrite
 2 * (w+w+α+β)
-
-# output
-2(2w + α + β)
 ```
 
 Note that writing a single tilde `~` as consequent, will make the rule return a dictionary of [slot variable, expression matched].
 
-```jldoctest rewrite
+```@example rewrite
 r = @rule (~x + (~y)^(~m)) => ~
 
 r(z+w^α)
-
-# output
-Base.ImmutableDict{Symbol, Any} with 5 entries:
-  :MATCH => z + w^α
-  :m     => α
-  :y     => w
-  :x     => z
-  :____  => nothing
-
 ```
 
 ### Predicates for matching
@@ -153,7 +112,7 @@ Similarly `~~x::g` is a way of attaching a predicate `g` to a segment variable.
 
 For example,
 
-```jldoctest pred
+```@example pred
 using SymbolicUtils
 @syms a b c d
 
@@ -163,69 +122,51 @@ r = @rule ~x + ~~y::(ys->iseven(length(ys))) => "odd terms";
 @show r(b + c + d)
 @show r(b + c + b)
 @show r(a + b)
-
-# output
-r(a + b + c + d) = nothing
-r(b + c + d) = "odd terms"
-r(b + c + b) = nothing
-r(a + b) = nothing
 ```
 
 
 ### Associative-Commutative Rules
 
 Given an expression `f(x, f(y, z, u), v, w)`, a `f` is said to be associative if the expression is equivalent to `f(x, y, z, u, v, w)` and commutative if the order of arguments does not matter.  SymbolicUtils has a special `@acrule` macro meant for rules on functions which are associate and commutative such as addition and multiplication of real and complex numbers.
 
-```jldoctest acr
+```@example acr
 using SymbolicUtils
 @syms x y z
 
 acr = @acrule((~a)^(~x) * (~a)^(~y) => (~a)^(~x + ~y))
 
 acr(x^y * x^z)
-
-# output
-x^(y + z)
 ```
 
 although in case of `Number` it also works the same way with regular `@rule` since autosimplification orders and applies associativity and commutativity to the expression.
 
 ### Example of applying the rules to simplify expression
 
 Consider expression `(cos(x) + sin(x))^2` that we would like simplify by applying some trigonometric rules. First, we need rule to expand square of `cos(x) + sin(x)`. First we try the simplest rule to expand square of the sum and try it on simple expression
-```jldoctest rewriteex
+```@example rewriteex
 using SymbolicUtils
 
 @syms x::Real y::Real
 
 sqexpand = @rule (~x + ~y)^2 => (~x)^2 + (~y)^2 + 2 * ~x * ~y
 
 sqexpand((cos(x) + sin(x))^2)
-
-# output
-sin(x)^2 + 2sin(x)*cos(x) + cos(x)^2
 ```
 
 It works. This can be further simplified using Pythagorean identity and check it
 
-```jldoctest rewriteex
+```@example rewriteex
 pyid = @rule sin(~x)^2 + cos(~x)^2 => 1
 
 pyid(sin(x)^2 + 2sin(x)*cos(x) + cos(x)^2)===nothing
-
-# output
-true
 ```
 
 Why does it return `nothing`? If we look at the expression, we see that we have an additional addend `+ 2sin(x)*cos(x)`. Therefore, in order to work, the rule needs to be associative-commutative.
 
-```jldoctest rewriteex
+```@example rewriteex
 acpyid = @acrule sin(~x)^2 + cos(~x)^2 => 1
 
 acpyid(cos(x)^2 + sin(x)^2 + 2cos(x)*sin(x))
-
-# output
-1 + 2sin(x)*cos(x)
 ```
 
 It has been some work. Fortunately rules may be [chained together](#chaining rewriters) into more sophisticated rewriters to avoid manual application of the rules.
@@ -270,7 +211,7 @@ Several rules may be chained to give chain of rules. Chain is an array of rules
 
 To check that, we will combine rules from [previous example](#example of applying the rules to simplify expression) into a chain
 
-```jldoctest composing
+```@example composing
 using SymbolicUtils
 using SymbolicUtils.Rewriters
 
@@ -282,52 +223,37 @@ acpyid = @acrule sin(~x)^2 + cos(~x)^2 => 1
 csa = Chain([sqexpand, acpyid])
 
 csa((cos(x) + sin(x))^2)
-
-# output
-1 + 2sin(x)*cos(x)
 ```
 
 Important feature of `Chain` is that it returns the expression instead of `nothing` if it doesn't change the expression
 
-```jldoctest composing
+```@example composing
 Chain([@acrule sin(~x)^2 + cos(~x)^2 => 1])((cos(x) + sin(x))^2)
-
-# output
-(sin(x) + cos(x))^2
 ```
 
 it's important to notice, that chain is ordered, so if rules are in different order it wouldn't work the same as in earlier example
 
-```jldoctest composing
+```@example composing
 cas = Chain([acpyid, sqexpand])
 
 cas((cos(x) + sin(x))^2)
-
-# output
-sin(x)^2 + 2sin(x)*cos(x) + cos(x)^2
 ```
 since Pythagorean identity is applied before square expansion, so it is unable to match squares of sine and cosine.
 
 One way to circumvent the problem of order of applying rules in chain is to use `RestartedChain`
 
-```jldoctest composing
+```@example composing
 using SymbolicUtils.Rewriters: RestartedChain
 
 rcas = RestartedChain([acpyid, sqexpand])
 
 rcas((cos(x) + sin(x))^2)
-
-# output
-1 + 2sin(x)*cos(x)
 ```
 
 It restarts the chain after each successful application of a rule, so after `sqexpand` is hit it (re)starts again and successfully applies `acpyid` to resulting expression.
 
 You can also use `Fixpoint` to apply the rules until there are no changes.
 
-```jldoctest composing
+```@example composing
 Fixpoint(cas)((cos(x) + sin(x))^2)
-
-# output
-1 + 2sin(x)*cos(x)
 ```

test/doctest.jl

@@ -4,7 +4,6 @@ using Pkg, Test, SafeTestsets
     if haskey(ENV, "SU_BENCHMARK_ONLY")
         @safetestset "Benchmark" begin include("benchmark.jl") end
     else
-        @safetestset "Doc" begin include("doctest.jl") end
         @safetestset "Basics" begin include("basics.jl") end
         @safetestset "Basics" begin include("arrayop.jl") end
         @safetestset "Order" begin include("order.jl") end