For developers

Building the documentation locally

Setup the docs folder environment

We assume that your terminal is located in the root folder of the GalerkingToolkit.jl repo. Open Julia, pointing to the docs folder.

$ julia --project=docs/

Develop your current copy of GalerkingToolkit.

julia> ]
(docs) pkg> dev .

You will need to do this each time the dependencies of the documentation or of GalerkinToolkit change.

Standard build

After the setup, exit package mode and run

julia> include("docs/make.jl")

This will take a while. When it is done, you will have the html docs in the folder docs/build.

Visualizing the documentation

The easiest way to visualize the documentation is using LiveServer as follows.

julia> using LiveServer
serve(dir="docs/build/")

After it, your docs will be served at the given url.

If nor yet done, you can install LiveServer as follows. We recommend to install it in your global environment.

julia> ]
pkg> activate
pgk> add LiveServer

The standard build takes a long time since it runs several examples. This delay makes this approach impractical to write documentation, since one needs to build the docs often to check the final result.

To avoid this, one can run all the files in docs/src/src_jl in advance using

julia> include("docs/make_media.jl")

and then one can quickly build the documentation with

julia> include("docs/make_with_media.jl")

This will work as long as you are not including new figures or animations that are generated by running the files in the docs/src/src_jl folder. Otherwise you will need to run the particular file with

julia> include("docs/src/src_jl/<file that generates the figure>.jl")

or running again

julia> include("docs/media.jl")

The output documentation is not exactly the same as the generated with the standard build method, but it is good enough for development.

Performance Benchmarks

There is a benchmark suite defined in GalerkinToolkitExamples/benchmarks. This uses BenchmarkTools.jl to perform the timings and github-action-benchmark to collect the results and store them in the benchmarks branch. Upon merging of a PR, and after the docs have built, the benchmark results are copied from the benchmarks branch into the gh-pages branch. This is required to prevent overwriting of the previous results by docs deployment etc.

Graphs of performance changes over time (per commit hash) can then be viewed here: https://galerkintoolkit.github.io/GalerkinToolkit.jl/dev/bench/.

The github action can be configured (in .github/workflows/CI.yml, job benchmark) to fail if the performance change is beyond a given threshold. Look for the alert-threshold: and fail-on-alert: keys.

More benchmarks can be added (or existing ones modified) in GalerkinToolkitExamples/benchmarks/run_benchmarks.jl.