Running the example phantom recon

[felixhorger]

I think the example for phantom recons needs some improvement. @cncastillo please can you cross-check that this is the right way to do it.

If I understood it correctly, there are two options that work as it is now, firstly I could activate the Project.toml of GIRFReco.jl by using julia --project=/path/to/GIRFReco.jl joss_example.jl (but that's not in the description), or I could have all the required dependencies installed into my main environment (which is active if I run it as described in the readme).
I think both are not optimal because you want the example to have a similar setup to when someone is using your package, but self-contained and with minimal effort to get it running. The first method activates the wrong environment, and the second requires the user to manually install packages they might not want/need into their main environment. I suggest setting up an environment which you ship with the joss_example.jl, i.e. in the examples folder you run ] activate ., and then add all the dependencies for the example and add the Project.toml to the git repo. The instructions then need to be adjusted to say cd .../examples/, then ] and activate, instantiate, then julia --project=. joss_example.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.