small api changes & update docs (#8)

* update README

* direct download link via source url

* Renamed ExampleLiterate to ExampleModule, links to packages

* v0.3.0

Project.toml

@@ -1,7 +1,7 @@
 name = "ExampleJuggler"
 uuid = "3bbe58f8-ed81-4c4e-a134-03e85fcf4a1a"
 authors = ["Jürgen Fuhrmann <juergen-fuhrmann@web.de>"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"

README.md

@@ -5,14 +5,84 @@
 
 # ExampleJuggler.jl
 
+This package also could be called "DocumenterExampleHandler.jl". It helps to maintain comprehensive complete (i.e. ready to download and run) code examples in Documenter.jl documentation.
 
-Following the [DRY mantra](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), provide tools for handling
-code examples in  various Julia packages.
+Code examples could be in plain Julia scripts, Julia scripts containing modules or pluto notebooks and serve three purposes:
+- Ready to be run by users
+- Part of CI tests
+- Well integrated into documenter based documentation (via [Literate.jl](/~https://github.com/fredrikekre/Literate.jl), [PlutoStaticHTML.jl](/~https://github.com/rikhuijzer/PlutoStaticHTML.jl) or [PlutoSliderServer.jl](/~https://github.com/JuliaPluto/PlutoSliderServer.jl))
+
+Maintaining a list of examples leads to considerable boilerplate ("example juggling" - that is why the name ...) in `test/runtest.jl` and `docs/make.jl`.
+This package helps to hide this boilerplate behind its API.
+
+## CI Tests
+
+With this package, `test/runtests.jl` can look  as follows:
+
+```julia
+using Test
+using ExampleJuggler
+
+ExampleJuggler.verbose!(true)
+
+example_dir = joinpath(@__DIR__, "..", "examples")
+
+modules = ["ExampleModule.jl"]
+notebooks = ["PlutoTemplate.jl", "ExamplePluto.jl"]
+scripts = ["testscript.jl", "PlutoTemplate.jl", "ExamplePluto.jl"]
+
+@testset "pluto notebooks" begin
+    @testplutonotebooks(example_dir, notebooks)
+end
+
+@testset "module examples" begin
+    @testmodules(example_dir, modules, a=2)
+end
+
+@testset "scripts + notebooks" begin
+    @testscripts(example_dir, scripts)
+end
+```
+
+## Documenter build
+With this package, `docs/make.jl` can look  as follows (please see [`docs/make.jl`](/~https://github.com/j-fu/ExampleJuggler.jl/blob/main/docs/make.jl) of this
+package for a more comprehensive setting):
+
+```julia 
+using Documenter, ExampleJuggler, CairoMakie
+
+DocMeta.setdocmeta!(ExampleJuggler, :DocTestSetup, :(using ExampleJuggler); recursive = true)
+
+example_dir = joinpath(@__DIR__, "..", "examples")
+
+modules = ["ExampleModule.jl"]
+
+notebooks = ["PlutoTemplate.jl"
+                 "Example with Graphics" => "ExamplePluto.jl"]
+
+cleanexamples()
+
+module_examples = @docmodules(example_dir, example_modules, Plotter=CairoMakie)
+
+html_examples = @docplutonotebooks(example_dir, notebooks
+
+makedocs(; sitename = "ExampleJuggler.jl",
+           modules = [ExampleJuggler],
+           format = Documenter.HTML(; size_threshold_ignore = last.(html_examples),
+                                      mathengine = MathJax3()),
+             authors = "J. Fuhrmann",
+             repo = "/~https://github.com/j-fu/ExampleJuggler.jl",
+             pages = [
+                 "api.md",
+                 "Modules" => module_examples,
+                 "Notebooks" => html_examples,
+             ])
+
+cleanexamples()
+
+deploydocs(; repo = "github.com/j-fu/ExampleJuggler.jl.git", devbranch = "main")
+
+end
+```
+In particular, graphics generation for module examples is supported.
 
-Aims of this package are:
-- Allow easy download and running of examples for users in form of Pluto notebooks or Julia scripts with modules.
-- Provide an easy ways to run examples in CI tests
-- Provide different ways to generate documentation from examples:
-   - `*.jl |> Literate.jl |> *.md`
-   - `pluto*.jl |> PlutoStaticHTML.jl |> *.md`
-   - `pluto*.jl |> PlutoSliderServer.jl |> *.html` with iframe embedding into markdown pages

docs/make.jl

@@ -7,7 +7,7 @@ function mkdocs()
 
     example_dir = joinpath(@__DIR__, "..", "examples")
 
-    modules = ["ExampleLiterate.jl"]
+    modules = ["ExampleModule.jl"]
 
     notebooks = ["PlutoTemplate.jl"
                  "Example with Graphics" => "ExamplePluto.jl"]

examples/ExampleLiterate.jl → examples/ExampleModule.jl

@@ -1,5 +1,5 @@
 #=
-# ExampleLiterate.jl
+# ExampleModule.jl
 
 ([source code](@__SOURCE_URL__))
 
@@ -11,7 +11,7 @@ via the [`ExampleJuggler.docmodules`](@ref) method.
 ![](mock_xt.svg)
 
 =#
-module ExampleLiterate
+module ExampleModule
 
 ismakie(Plotter::Any) = false
 ismakie(Plotter::Module) = isdefined(Plotter, :Makie)

src/modules.jl

@@ -42,27 +42,25 @@ macro plotmodules(example_dir, modules, kwargs...)
 end
 
 """
-         docmodules(example_sources;
-                     source_prefix = "/~https://github.com/j-fu/ExampleJuggler.jl/blob/main/examples")
+         docmodules(example_sources; kwargs...)
 
-Generate markdown files for use with documenter from list of Julia code examples.
-See [ExampleLiterate.jl](@ref) for an example.
+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;
-                    source_prefix = "/~https://github.com/j-fu/ExampleJuggler.jl/blob/main/examples")
+function docmodules(example_dir, modules; kwargs...)
     md_dir = example_md_dir(module_examples)
     modulelist = homogenize_notebooklist(modules)
     modules = last.(modulelist)
     example_sources = joinpath.(example_dir, modules)
     example_md = String[]
     for example_source in example_sources
+        cp(example_source, joinpath(example_md_dir(ExampleJuggler.module_examples), basename(example_source)))
         example_base, ext = splitext(example_source)
         if ext == ".jl"
-            source_url = source_prefix * "/" * basename(example_source)
             Literate.markdown(example_source,
                               md_dir;
                               info = verbose(),
-                              preprocess = buffer -> replace_source_url(buffer, source_url))
+                              preprocess = buffer -> replace_source_url(buffer, basename(example_source)))
         else
             @warn "$(example_source) appears to be not a Julia file, skipping"
         end
@@ -74,12 +72,13 @@ end
 """
     @docmodules(example_dir, modules, kwargs...)
 
-Generate markdown files and plots for use with documenter from list of Julia module code examples.
-See [ExampleLiterate.jl](@ref) for an example. `kwargs` are passed to the `generateplots` method
-of the corresponding module source.
+Generate markdown files and plots for use with documenter from list of Julia modules.
+Wrapper macro for [`docmodules`](@ref).
 """
 macro docmodules(example_dir, modules, kwargs...)
-    esc(:(ExampleJuggler.@plotmodules(example_dir, modules, $(kwargs...)); ExampleJuggler.docmodules(example_dir, modules)))
+    esc(:(ExampleJuggler.@plotmodules(example_dir, modules, $(kwargs...));
+          ExampleJuggler.docmodules(example_dir, modules;
+                                    $(kwargs...))))
 end
 
 """

src/pluto.jl

@@ -91,11 +91,11 @@ Keyword arguments:
   As a consequence, if this default is kept, it is necessary to have all package dependencies of the
   notebooks in the package environment.
 - `iframe`: boolean (default: false). 
-    - If `true`, html files are produced from the notebooks via `PlutoSliderServer.jl`, similar to Pluto's
+    - If `true`, html files are produced from the notebooks via [PlutoSliderServer.jl](/~https://github.com/JuliaPluto/PlutoSliderServer.jl), similar to Pluto's
       html export. For documenter, a markdown page is created which contains statements to show the 
       notebook html in an iframe. The advantage of this method is that active javascript content is shown.
       The disadvantage is weak integration into documenter.
-    - If false, Documenter markdown files are ceated via `PlutoStaticHTML.jl`. These integrate well with
+    - If false, Documenter markdown files are ceated via  [PlutoStaticHTML.jl](/~https://github.com/rikhuijzer/PlutoStaticHTML.jl). These integrate well with
       Documenter, but are (as of now) unable to show active javascript content. Graphics is best prepared
       with CairoMakie.
 - `source_prefix`: Path prefix to the notebooks on github (for generating download links)

src/plutosliderserver.jl

@@ -1,7 +1,7 @@
 """
     docplutosliderserver(example_dir, notebooks; pluto_project, source_prefix, iframe_height)
 
-Document notebooks via plutosliderserver.
+Document notebooks via  [PlutoSliderServer.jl](/~https://github.com/JuliaPluto/PlutoSliderServer.jl)
 """
 function docplutosliderserver(example_dir, notebooks;
                               source_prefix = "/~https://github.com/j-fu/ExampleJuggler.jl/blob/main/examples",
@@ -24,10 +24,11 @@ function docplutosliderserver(example_dir, notebooks;
 
     for notebook in notebooks
         base = splitext(basename(notebook))[1]
+        cp(joinpath(example_dir, notebook), joinpath(example_md_dir(ExampleJuggler.pluto_examples), basename(notebook)))
         mdstring = """
 ##### [$(base).jl](@id $(base))
 
-[Download]($(source_prefix)/$(basename(notebook))) this [Pluto.jl](https://plutojl.org)  notebook.
+[Download]($(basename(notebook))) this [Pluto.jl](https://plutojl.org)  notebook.
 
 ```@raw html
 <iframe style="height:$(iframe_height)" width="100%" src="../$(base).html"> </iframe>

src/plutostatichtml.jl

@@ -1,7 +1,7 @@
 """
     docplutostatichtml(example_dir, notebooks; pluto_project)
 
-Document notebooks via plutostatichtml.
+Document notebooks via  [PlutoStaticHTML.jl](/~https://github.com/rikhuijzer/PlutoStaticHTML.jl).
 """
 function docplutostatichtml(example_dir, notebooks; pluto_project = Base.active_project())
     project = Base.active_project()

test/runtests.jl

@@ -5,7 +5,7 @@ ExampleJuggler.verbose!(true)
 
 example_dir = joinpath(@__DIR__, "..", "examples")
 
-modules = ["ExampleLiterate.jl"]
+modules = ["ExampleModule.jl"]
 notebooks = ["PlutoTemplate.jl", "ExamplePluto.jl"]
 scripts = ["testscript.jl", "PlutoTemplate.jl", "ExamplePluto.jl"]