Running the example phantom recon about girfreco.jl

[alexjaffray]

@felixhorger yes, we only ever tested this from inside the GIRFReco environment, and didn't adjust the example after package-ization during the JOSS pre-review. I will adjust as per your final suggestion.

[cncastillo]

There are multiple ways of distributing the examples.

Option 1: Use the same environment as docs

In general, the documentation should have its own Project.toml. So to run the example it would be like this

julia --project=docs/ docs/lit/examples/joss_demo.jl

This is similar to what the CI does to generate the docs with GitHub actions. But really it should just work if I download it and run it.

Option 2: Use Literate to generate a Julia file that installs everything for you

In literate you can add special comments #jl (code that will be present only in the generated Julia file), #md (code that will only be in the generated docs), and #nb (for jupyter notebooks). So you can install the packages for the user in a temporary environment.

# This is text that will be present in the docs explaining the code
#jl using Pkg; Pkg.activate(; temp = true); Pkg.add("Package1"); Pkg.add("Package2")
using Package1, Pacakge2
im = recon(data)
p = plot_image(im)
#md savefig(p, "../assets/results.html") # hide
#jl display(p)
#md # ```@raw html
#md # <object type="text/html" data="../../assets/results.html"></object>
#md # ```

The link to the generated files can be added programmatically, see this as an example.

Option 3: Using Manifest.toml and Project.toml to set an environment for an specific example

If you really want a specific example to have a self-contained and reproducible environment you could add a Project.toml and Manifest.toml to docs/lit/examples/ (I think the Manifest.toml is enough). If you cd to that folder and open julia

(@v1.9) pkg> activate .
(@v1.9) pkg> instantiate
julia> include("joss_demo.jl")

But not sure how it will play with Literate if that environment is different from the one in docs (I would make my life easier and use the same environment).

Option 4: Use Pluto for self-contained environments

Another option is putting the example as a Pluto.jl notebook, this could be the best for reproducibility and ease of use because it contains its own Project.toml and Manifest.toml, can also be run as a normal Julia file and exported as plain HTML.

nb_path = "..."
s = Pluto.ServerSession();
nb = Pluto.SessionActions.open(s, nb_path; run_async=false)
html_contents = Pluto.generate_html(nb; binder_url_js="undefined")
open("test_pluto.html", "w") do io
    write(io, html_contents)
end

or opened like a notebook

using Pluto
Pluto.run() #Opens a tab in your browser that you could use to open the notebook

There could be more ways that I haven't thought but that is the jist of it.

[alexjaffray]

#9 will be addressed here as well

[alexjaffray]

#16

[alexjaffray]

We have elected to pursue Option 1 for reducing the dependencies and also to streamline the running of the examples. This will achieve the target of a significantly more lightweight GIRFReco.jl. We will make this change and close this issue once completed.

[alexjaffray]

We have implemented Option 1 into #4, and so are closing this.