I’m having trouble figuring out what I need to do to use Pluto notebooks as source code, especially regarding the package environment and Pluto’s package manager.
Do I need PlutoDevMacros.jl and/or @skip_as_script? I see “skip_as_script” inside Pluto comments in the provided example notebooks, but I do not see the macro at all when viewed as a notebook. How did you add these special comments? Is there documentation on this?
Do I need to add Markdown, InteractiveUntils, and Pluto as dependencies of my package environment, so every package used is in the Project.toml? Or can I do the opposite: have no package dependencies and leave everything to the Pluto package manager somehow? Should I be disabling the Pluto package manager with some sort of Pkg.activate command in the notebook?
Example
Basically, what should I change below and what should I have in this Project.toml so that I can:
Load MyPackage.jl and call MyPackage.f(x).
Run the notebook independently to view the rendered math.
MyPackage.jl
module MyPackage
include("MyPackageNotebook.jl")
end #module
MyPackageNotebook.jl
using Latexify
md"This is an *equation* for `f(x)`."
@latexrun f(x) = x^2
(I’m also curious about how to set up the package Test folder and test dependencies, but that is probably another topic.)
While PlutoDevMacros.jl can be used to simplify package development with notebooks, it is not necessary to use that (and in basically no case you should have Pluto as a dependency)
For what concern @skip_as_script I’d say that for most use cases the embedded functionality in Pluto to comment out cells (via the three dots context menu at the top right of the cell) in the file is easier to use as it automatically tracks cells dependencies when commenting out cells.
You also definitely want to handle the package environment independently of the Pluto notebook as the package itself has no interaction with the Pluto pkg manager and would simply throw an error during precompilaton the moment it encounters the first using inside the notebook you included.
Whether you prefer at that point to skip the pluto pkg manager altogether is up to you, I find it easier but then you lose standalone reproducibility of the notebook file when it’s outside the package folder.
As markdown and interactiveutils are used by default by each notebook file, you should also include those in your package environment to avoid errors during precompilaton.
Overall for simple packages including one notebook only or stand alone notebooks I second @j-fu suggestion to look at PlutoUI.jl, if you want to do more complex packages with multiple interdependent notebooks then you will find it easier with PlutoDevMacros.jl.
In that case you can find some examples in the test folder of PlutoDevMacros.jl and specifically at the TestPackage subfolder of the tests which is an example of a semi complex package built using notebooks via PlutoDevMacros.jl (I originally developed PlutoDevMacros.jl for this purpose but I now use the is just to simplify interactive package development. I know believe that building packages out of interconnected notebooks is not the best approach for maintainability)
That is one cell that you should indeed skip with the embedded pluto functionality (if you check the actual source you see the cell is commented out with the Metadata skip_as_script = true)
To do so you have to open the cell context menu and select the disable in file option (not at the pc at the moment so I can’t make a screenshot)
Okay, I found the button, and it is working now. I didn’t expect to get an error with it enabled in the Pluto notebook itself though. I thought disable in file would only affect when the code is run outside the notebook environment?
The problem is that if you don’t disable it in the file, when you include the notebook in the package it also executes that cell and throws an error because pkg is not a dependency of your package.
So the error you see in Pluto is not generated inside Pluto itself but just when you activate the package environment in the notebook and instantiate it, which triggers the error during precompilaton
