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.

7

It appears that the problem is the eegplot function attempting to detect the screen size using GLFW, and this hangs in a headless CI environment.

Also, the function calls display(fig), which may cause problems in headless mode with CairoMakie.

I’ve made the following changes:

  • Added JULIA_PLOT_HEADLESS: “true” to the CI environment in docs.yml to skip GLFW monitor detection.

  • Modified eegplot in EEGPlot.jl to conditionally call display(fig) only when not in headless mode.

With these changes it works. Thanks for the help and the DEBUG trick.

1 Like
8

Maybe good to know for @sdanisch as well if this ever pops up again.