docs: expand structured expression example

Author: MilesCranmer

docs/make.jl

@@ -40,9 +40,6 @@ index_content = let r = read(readme, String)
     bottom_part = """
     ## Contents
 
-    ```@contents
-    Pages = ["utils.md", "api.md", "eval.md"]
-    ```
     """
 
     join((top_part, r, bottom_part), "\n")
@@ -62,6 +59,13 @@ makedocs(;
     format=Documenter.HTML(;
         canonical="https://symbolicml.org/DynamicExpressions.jl/stable"
     ),
+    pages=[
+        "Home" => "index.md",
+        "Eval" => "eval.md",
+        "Examples" => ["examples/structured_expression.md"],
+        "Utils" => "utils.md",
+        "API" => "api.md",
+    ],
 )
 
 # Forward links from old docs:

docs/utils.jl

@@ -48,13 +48,13 @@ function process_literate_block(output_file, content, source_file)
     write(temp_file, content)
 
     # Process the temporary file with Literate.markdown
-    output_dir = joinpath(@__DIR__, "src")
+    output_dir = joinpath(@__DIR__, "src", "examples")
     base_name = first(splitext(basename(output_file))) # Remove any existing extension
 
     markdown(temp_file, output_dir; name=base_name, documenter=true)
 
     # Generate the relative path for EditURL
-    edit_path = relpath(source_file, joinpath(@__DIR__, "src"))
+    edit_path = relpath(source_file, output_dir)
 
     # Read the generated markdown file
     md_file = joinpath(output_dir, base_name * ".md")

test/test_structured_expression.jl

@@ -79,7 +79,7 @@ end
 end
 
 @testitem "StructuredExpression Literate examples" begin
-    #literate_begin file="src/structured_expression.md"
+    #literate_begin file="src/examples/structured_expression.md"
     #=
     # `StructuredExpression` example
 
@@ -89,22 +89,20 @@ end
 
     Let's look at an example:
     =#
-    using DynamicExpressions
-    using Test
+    using DynamicExpressions, Random
 
     # First, we will create some normal `Expression` objects.
 
     operators = OperatorEnum(; unary_operators=(cos, exp), binary_operators=(+, -, *, /))
     variable_names = ["x", "y"]
     x = Expression(Node{Float64}(; feature=1); operators, variable_names)
     y = Expression(Node{Float64}(; feature=2); operators, variable_names)
-    @test typeof(x) <: AbstractExpression{Float64,<:Node{Float64}}
+    @test typeof(x) <: AbstractExpression{Float64,<:Node{Float64}}  #src
 
     typeof(x)
     #=
-    `AbstractExpression` can be composed together using standard Julia
-    operations. For example, let's create two complex expressions from these,
-    and check that they have the same type:
+    Any `AbstractExpression`, such as this `Expression` object, can be composed together
+    using standard Julia math operations. For example, let's some complex expressions from these:
     =#
     f = x * x - cos(2.5f0 * y + -0.5f0)
     g = exp(2.0 - y * y)
@@ -117,8 +115,8 @@ end
     expressions during evaluation.
     =#
     ex = StructuredExpression((; f, g), nt -> nt.f + nt.g)
-    @test typeof(ex) <: AbstractExpression{Float64,<:Node{Float64}}  #src
     ex
+    @test typeof(ex) <: AbstractExpression{Float64,<:Node{Float64}}  #src
     #=
     Note that this is displayed as a single tree, with the `+` operator
     used to combine them. Despite this, the expression is not actually
@@ -130,6 +128,25 @@ end
     =#
     length(get_tree(ex))
     @test length(get_tree(ex)) == 17  #src
+    #=
+    Evaluation of an `AbstractExpression` is set up to forward through
+    `get_tree`, so this will work automatically.
+
+    Let's try to evaluate this on some random data:
+    =#
+    rng = Random.MersenneTwister(0)
+    X = randn(rng, Float64, 2, 5)
+    X
+    #=
+    Followed by the evaluation. Since we have stored the operators directly
+    in the expression object, we do not need to pass the operators explicitly:
+    =#
+    ex(X)
+    #=
+    Which we can verify against the individual expressions:
+    =#
+    f(X) + g(X)
+    @test ex(X) ≈ f(X) + g(X) #src
 
     #literate_end
 end