Docscripts (#11)

* fixes #10 * allow to document scripts as well * rename testscript * Project.toml
j-fu · Nov 23, 2023 · b5c78c4 · b5c78c4 · j-fu · Nov 23, 2023
1 parent aa39bb6
commit b5c78c4
Show file tree

Hide file tree

Showing 10 changed files with 92 additions and 23 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ExampleJuggler"
 uuid = "3bbe58f8-ed81-4c4e-a134-03e85fcf4a1a"
 authors = ["Jürgen Fuhrmann <juergen-fuhrmann@web.de>"]
-version = "0.3.3"
+version = "0.4"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"

diff --git a/docs/make.jl b/docs/make.jl
@@ -7,13 +7,15 @@ function mkdocs()
 
     example_dir = joinpath(@__DIR__, "..", "examples")
 
+    scripts = ["ExampleScript.jl"]
     modules = ["ExampleModule.jl"]
 
     notebooks = ["PlutoTemplate.jl"
                  "Example with Graphics" => "ExamplePluto.jl"]
 
     cleanexamples()
 
+    script_examples = @docscripts(example_dir, scripts)
     module_examples = @docmodules(example_dir, modules, Plotter=CairoMakie)
     html_examples = @docplutonotebooks(example_dir, notebooks, iframe=false)
     pluto_examples = @docplutonotebooks(example_dir, notebooks, iframe=true)
@@ -30,6 +32,7 @@ function mkdocs()
                  "Home" => "index.md",
                  "api.md",
                  "Modules" => module_examples,
+                 "Scripts" => script_examples,
                  "Notebooks" => html_examples,
                  "Notebooks in iframe" => pluto_examples,
                  "mock.md",

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -7,15 +7,16 @@
 ## Documentation
 ```@docs
 @docmodules
+@docscripts
 docplutonotebooks
 @docplutonotebooks
 ```
 
 ## Testing
 ```@docs
-testplutonotebooks
-@testplutonotebooks
 @testmodules
 @testscripts
+testplutonotebooks
+@testplutonotebooks
 ```
 
diff --git a/examples/ExampleScript.jl b/examples/ExampleScript.jl
@@ -0,0 +1,38 @@
+#=
+# Script example
+=#
+
+#
+# Import stuff
+#
+using Pkg
+using ExampleJuggler
+import CairoMakie
+using Test
+#
+# Run stuff
+#
+
+x, fx = mock_x()
+maxfx = maximum(fx)
+
+#
+# Plot of the  result
+# ![](ExampleScript.svg)
+#
+# We can test when the script runs
+@test isapprox(maxfx, 1.0; rtol = 1.0e-3)
+
+# If we don't want the tests in the script we 
+# can test in the runtests function
+function runtests(; kwargs...)
+    println("runtests from  testscript")
+    @test isapprox(maxfx, 1.0; rtol = 1.0e-3)
+end
+
+# Here we generate plots
+function generateplots(dir; kwargs...)
+    CairoMakie.activate!(; type = "svg", visible = false)
+    p = CairoMakie.lines(x, fx)
+    CairoMakie.save(joinpath(dir, "ExampleScript.svg"), p)
+end
diff --git a/examples/testscript.jl b/examples/testscript.jl
diff --git a/src/ExampleJuggler.jl b/src/ExampleJuggler.jl
@@ -19,7 +19,7 @@ include("modules.jl")
 export @docmodules, @testmodules
 
 include("scripts.jl")
-export @testscripts
+export @docscripts, @testscripts
 
 include("pluto.jl")
 export testplutonotebooks, @testplutonotebooks, docplutonotebooks, @docplutonotebooks

diff --git a/src/common.jl b/src/common.jl
@@ -6,10 +6,11 @@ function verbose!(v::Bool)
     verbosity = v
 end
 
+const script_examples = "script_examples"
 const module_examples = "module_examples"
 const pluto_examples = "pluto_examples"
 const plutostatichtml_examples = "plutostatichtml_examples"
-const all_examples = [module_examples, pluto_examples, plutostatichtml_examples]
+const all_examples = [module_examples, pluto_examples, plutostatichtml_examples, script_examples]
 
 function cleanexamples()
     for examples in all_examples

diff --git a/src/modules.jl b/src/modules.jl
@@ -23,7 +23,7 @@ macro plotmodule(source, kwargs...)
           if isdefined(mod, :generateplots)
               ExampleJuggler.verbose() && @info "generating plots for " * normpath($(source))
               Base.invokelatest(getproperty(mod, :generateplots), ExampleJuggler.example_md_dir(ExampleJuggler.module_examples);
-                           $(kwargs...))
+                                $(kwargs...))
           end))
 end
 
@@ -50,16 +50,16 @@ end
 Generate markdown files for use with documenter from list of Julia code examples via [Literate.jl](/~https://github.com/fredrikekre/Literate.jl).
 See [ExampleModule.jl](@ref) for an example.
 """
-function docmodules(example_dir, modules; kwargs...)
-    md_dir = example_md_dir(module_examples)
+function docmodules(example_dir, modules; x_examples = module_examples, kwargs...)
+    md_dir = example_md_dir(x_examples)
     modulelist = homogenize_notebooklist(modules)
     modules = last.(modulelist)
     example_sources = joinpath.(example_dir, modules)
     example_md = String[]
     for example_source in example_sources
         example_base, ext = splitext(example_source)
         if ext == ".jl"
-            cp(example_source, joinpath(example_md_dir(ExampleJuggler.module_examples), basename(example_source)))
+            cp(example_source, joinpath(example_md_dir(x_examples), basename(example_source)))
             Literate.markdown(example_source,
                               md_dir;
                               documenter = false,
@@ -68,7 +68,7 @@ function docmodules(example_dir, modules; kwargs...)
         else
             @warn "$(example_source) appears to be not a Julia file, skipping"
         end
-        push!(example_md, joinpath(module_examples, splitext(basename(example_source))[1] * ".md"))
+        push!(example_md, joinpath(x_examples, splitext(basename(example_source))[1] * ".md"))
     end
     Pair.(first.(modulelist), example_md)
 end

diff --git a/src/scripts.jl b/src/scripts.jl
@@ -29,3 +29,36 @@ macro testscripts(example_dir, sources, kwargs...)
             end
         end)
 end
+
+macro plotscript(source, kwargs...)
+    esc(:(mod = eval(ExampleJuggler.parsescript($(source)));
+          if isdefined(mod, :generateplots)
+              ExampleJuggler.verbose() && @info "generating plots for " * normpath($(source))
+              Base.invokelatest(getproperty(mod, :generateplots), ExampleJuggler.example_md_dir(ExampleJuggler.script_examples);
+                                $(kwargs...))
+          end))
+end
+
+macro plotscripts(example_dir, modules, kwargs...)
+    esc(quote
+            sources = last.(ExampleJuggler.homogenize_notebooklist($(modules)))
+            for source in sources
+                base, ext = splitext(source)
+                if ext == ".jl"
+                    ExampleJuggler.@plotscript(joinpath($example_dir, source), $(kwargs...))
+                end
+            end
+        end)
+end
+
+"""
+    @docscripts(example_dir, modules, kwargs...)
+
+Generate markdown files and plots for use with documenter from list of Julia modules.
+Wrapper macro for [`docmodules`](@ref).
+"""
+macro docscripts(example_dir, modules, kwargs...)
+    esc(:(ExampleJuggler.@plotscripts($example_dir, $modules, $(kwargs...));
+          ExampleJuggler.docmodules($example_dir, $modules; x_examples = ExampleJuggler.script_examples,
+                                    $(kwargs...))))
+end
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -7,16 +7,20 @@ example_dir = joinpath(@__DIR__, "..", "examples")
 
 modules = ["ExampleModule.jl"]
 notebooks = ["PlutoTemplate.jl", "ExamplePluto.jl"]
-scripts = ["testscript.jl", "PlutoTemplate.jl", "ExamplePluto.jl"]
+scripts = ["ExampleScript.jl"]
 
 @testset "pluto notebooks" begin
     @testplutonotebooks(example_dir, notebooks)
 end
 
+@testset "notebooks as scripts" begin
+    @testscripts(example_dir, notebooks)
+end
+
 @testset "module examples" begin
     @testmodules(example_dir, modules, a=2)
 end
 
-@testset "scripts + notebooks" begin
+@testset "scripts" begin
     @testscripts(example_dir, scripts)
 end