API

@docmodules(example_dir, modules, kwargs...)

Generate markdown files and plots (via the respective generateplots methods) for use with documenter from list of Julia modules. Wrapper macro for docmodules and ExampleJuggler.@plotmodules.

Parameters:

• example_dir: subdirectory where the files coresponding to the modules reside.
• modules: Vector of file names or pairs "title" => "filename" as in Documenter.jl.

Keyword arguments:

• use_module_titles: use titles from module input files
• other kwargs are passed to the optional generateplots method in the module.

@docscripts(example_dir, scripts, kwargs...)

Generate markdown files and plots (via the respective generateplots methods) for use with documenter from list of Julia scripts. Wrapper macro for ExampleJuggler.@plotscripts and docmodules.

Parameters:

• example_dir: subdirectory where the files coresponding to the modules reside.
• scripts: Vector of file names or pairs "title" => "filename" as in Documenter.jl.

Keyword arguments:

• use_script_titles: use titles from script input files
• Other keyword arguments can be used to pass information to generateplots of each of the scripts.

docplutonotebooks(example_dir, notebooks, kwargs...)

Parameters:

• notebooks: vector of pathnames or pairs of pathnames and strings pointing to notebooks to be tested.

Keyword arguments:

• pluto_project: if not nothing, this is passed via ENV["PLUTO_PROJECT"] to the notebooks with the possibility to activate it. By default it has the value of Base.active_project() which in practice is the environment runtests.jl is running in. 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 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. Prerequisite is import PlutoSliderServer in docs/make.jl.
  • If false, Documenter markdown files are ceated via PlutoStaticHTML.jl. These integrate well with Documenter, but are (as of now) unable to show active javascript content. Graphics is best prepared with CairoMakie. Prerequisite is import PlutoStaticHTML in docs/make.jl.
• distributed: Use parallel evaluation when iframe==false
• append_build_context: pass this to PlutoStaticHTML.OutputOptions. Possibly needed when running the notebook in external environment.
• source_prefix: Path prefix to the notebooks on github (for generating download links) Default: "https://github.com/j-fu/ExampleJuggler.jl/blob/main/examples".
• iframe_height: Height of the iframe generated. Default: "500px".

Return value: Vector of pairs of pathnames and strings pointing to generated markdown files for use in Documenter.makedocs()

@docplutonotebooks(example_dir, notebooklist, kwargs...)

Macro wrapper for docplutonotebooks. Just for aestethic reasons, as other parts of the API have to be macros.

cleanexamples()

Clean intermediate files from example documentation.

verbose(true_or_false)

Set verbosity

@testmodules(example_dir,modules, kwargs...)

Test several scripts defining modules via @testmodule.

@testscripts(example_dir, scripts, kwargs...)

Run scripts in the context of the calling module via @testscript

 testplutonotebooks(example_dir, notebooks; kwargs...)

Test pluto notebooks as notebooks in a pluto session which means that the notebook code is run in an extra process. Implemented in an extension triggered by using Pluto.

The method tracks Test.@test statements in notebook cells via testing errors of failed cells. The method does not invoke eventual runteststs() methods in the notebooks.

Parameters:

• example_dir: subdirectory with examples
• notebooks: vector of pathnames of notebooks to be tested.

Keyword arguments:

• pluto_project: if not nothing, this is passed via ENV["PLUTO_PROJECT"] to the notebooks. By default it has the value of Base.active_project() which in practice is the environment runtests.jl is running in. As a consequence, if this default is kept, it is necessary to have all package dependencies of the notebooks in the package environment. In a notebook it can be activated like:

    import Pkg as _Pkg
    haskey(ENV, "PLUTO_PROJECT") && _Pkg.activate(ENV["PLUTO_PROJECT"])

 @testplutonotebooks(example_dir,notebooks,  kwargs...)

Macro wrapper for testplutonotebooks. Just for aestethic reasons, as other parts of the API have to be macros.