Makie.jl - Deploying docs with Documenter.jl

Specific Domains Visualization
1

I am writing a package for plotting time series. The code is here.

The package depends on Makie and GLFW, not on a specific backend, as the plotting function eegplot works differently with the CairoMakie and GLMakie backend.

The documentation, instead, using Documenter, depends on CairoMakie and produces some static plots using ```example blocks. The documentation builds locally. When trying to deploy, I have all sorts of errors. The further i can go is using the docs.yml of Makie, but then the build is stuck at

...
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.

and runs forever.

The docs.yml output is here

Any help would be appreciated.
In the meanwhile i have deployed the docs manually.

2

What errors specifically?

This step is known to take a very long time. If you have many plots it can take an hour.

You could try setting draft=true to speedup the rendering. Then for a page you want to see put Draft=false in the meta block.

3

The local build taks a few minutes. the documentation creates three plots only, so i don’t think it is a matter of waiting more. I will leave it a while though.

As per the errors, if i use a standard docs.yml, i have errors way before in the process, related to GLFW not finding a display

4

I have no clue why it would hang, so more debug info would be needed. You can enable global debugging with: Logging · The Julia Language

ENV["JULIA_DEBUG"] = "all"

should do the trick

Or just for Documenter:

ENV["JULIA_DEBUG"] = "Documenter"
5

I did. It is stuck the first time it calls the eegplot function of the package to produce a plot in the first ```@example block:

┌ Debug: Running ExpanderPipeline on index.md
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/expander_pipeline.jl:55
┌ Debug: Evaluating @example block:
│ using EEGPlot, Eegle, CairoMakie
│ 
│ # read example EEG data, sampling rate and sensor labels from Eegle
│ X, sr = readASCII(EXAMPLE_Normative_1), 128;
│ sensors = readSensors(EXAMPLE_Normative_1_sensors);
│ 
│ # plot EEG
│ eegplot(X, sr, sensors; fig_size=(814, 450)) 
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/expander_pipeline.jl:860
6

I have not yet seen CairoMakie get stuck in Documenter builds, are you doing anything unusual?

For GLMakie, you need a gpu available so the Makie CI uses xvfb to pretend there’s one on the github actions runners. You don’t need that for CairoMakie.