Include the main example as page in docs

[JMulder99]

Fixes #12 and adds the example as part of the docs, which runs the code and plots the output directly in the HTML.

[tamasgal]

Looks good! Can you remove the Manifest from the docs? I will try to run it later as well and then we can merge 😃

[JMulder99]

What is the best way to delete the file?

I did not add the file, just updated after adding the packages. It was added in commit 9551b07

[tamasgal]

Sorry Jelmer, was super busy (we have the KM3NeT bootcamp this week as well). I'd suggest to simply delete it with git rm docs/Manifest.jl and then commit. The file will be recreated anyways if you do instantiate the package :)

[tamasgal]

I just removed the Manifest.toml from the docs.

For some reason, the doc building is stuck at the ExpandTemplates step. I am trying to figure out why...

~/Dev/Neurthino.jl make_example_work*
❯ make doc
make -C docs/
julia --project=. -e 'import Pkg; Pkg.develop(path=".."); Pkg.instantiate()'
   Resolving package versions...
  No Changes to `~/Dev/Neurthino.jl/docs/Project.toml`
  No Changes to `~/Dev/Neurthino.jl/docs/Manifest.toml`
julia --project=. make.jl
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.

...
...
hangs...

[tamasgal]

OK, I hunted it down to the for-loop which creates the plots. For some reason, that one is hanging for me in the background when the examples are executing while building the doc.

for (k, startFlav) in enumerate([L"\nu_e", L"\nu_\mu", L"\nu_\tau"])
    for (l, endFlav) in enumerate([L"\nu_e", L"\nu_\mu", L"\nu_\tau"])

        # create an oscillogram for every start- and endFlav combination
        p = heatmap(energies*u"GeV", coszenith, data_points[k,l,:,:], xscale=:log10,
            xlabel="Energy", ylabel=L"\cos(\theta_z)", title=latexstring(startFlav, L"\rightarrow", endFlav),
            clim=(0,1));

        # save each plot
        filename = "water_nu_$(k)_nu_$(l).svg"
        savefig(p, filename)

    end
    # instead of showing the output for each flavour, we break here
    break
end

I don't know why this happens, maybe related to the backend of Plots? I see a gksqt process popping up in the macOS dock when building the docs. I'll now try to use CairoMakie.

[tamasgal]

Anyways, it builds on the CI, so let's go on for now ;)

[JMulder99]

Great!

Building the docs worked fine for me (on Windows). So I don't know what could cause the issue.