diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 66a21e960a..d8fae36377 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -12,6 +12,13 @@ Quarto supports executable Julia code blocks within markdown. This allows you to Quarto has two available engines for executing Julia code. The older one is using the [IJulia](https://github.com/JuliaLang/IJulia.jl) Jupyter kernel and depends on Python to run. The newer engine is using the [QuartoNotebookRunner.jl](https://github.com/PumasAI/QuartoNotebookRunner.jl/) package to render notebooks and does not have any additional dependencies beyond a Julia installation. +Using either of these engines will require manually installing Julia if +you have not done so already. You can download it from +https://julialang.org/downloads/. There are two options for installation: the +Juliaup installation manager, or the "manual" installation approach. Unless +you know that you need to use the "manual" approach, use +Juliaup since it allows you to manage multiple Julia versions on your system. + ## Using the `jupyter` engine Below we'll describe how to [install](#installation) IJulia and related requirements but first we'll cover the basics of creating and rendering documents with Julia code blocks. @@ -318,6 +325,148 @@ The currently available options are: - `exeflags`: An array of strings which are appended to the `julia` command that starts the worker process. For example, a notebook is run with `--project=@.` by default (the environment in the directory where the notebook is stored) but this could be overridden by setting `exeflags: ["--project=/some/directory/"]`. - `env`: An array of strings where each string specifies one environment variable that is passed to the worker process. For example, `env: ["SOMEVAR=SOMEVALUE"]`. +### `juliaup` integration + +[`juliaup`](https://github.com/JuliaLang/juliaup) is the recommended way to +install and manage Julia versions. The `julia` engine supports using +`juliaup`'s `+` channel specifier to select the Julia version that a notebook +uses. This allow users to run several notebooks concurrently with different +Julia versions on the same machine without the need for customizing their +`PATH` in any way. + +To use this feature, ensure that you have used `juliaup` to install the channels +that you wish to use in your notebooks. Then add the channel specifier to the notebook +frontmatter in the `julia.exeflags` option: + +````markdown +--- +title: "A Julia 1.11 notebook" +engine: julia +julia: + exeflags: ["+1.11"] +--- + +```{{julia}} +VERSION +``` +```` + +`QuartoNotebookRunner` currently supports running Julia versions from 1.6 +onwards. Support for earlier versions is not planned. + +### Revise.jl integration + +[Revise](https://github.com/timholy/Revise.jl) allows for automatically +updating function definitions in Julia sessions. It is an essential tool in the +Julia ecosystem for any user that wishes to develop their own packages or large +projects. The `julia` engine supports using `Revise` within notebook processes +by simply importing the package into a cell at the start of a notebook. Once +imported `Revise` will automatically update functions imported from locally +developed packages in the same way as it behaves in a Julia REPL. + +Ensure that `Revise` is installed in the project environment that the notebook +is using, since the global environment is not included in the load path +provided to Julia, unlike the behaviour of a Julia REPL session. + +### Caching {#caching-julia} + +The engine has built-in support for caching notebook results. This feature is disabled by +default but can be enabled by setting the `execute.cache` option to `true` in a notebook's +frontmatter: + +````markdown +--- +title: "A caching example" +engine: julia +execute: + cache: true +--- + +```{{julia}} +rand() +``` +```` + +Notebook caches are invalidated based on the following criteria: + +- Using a different Julia version to run the notebook. +- Changes to the `Manifest.toml` of the environment the notebook is run in. Adding, removing, or changing package versions will invalidate the cache. +- Changing any contents in the notebook's frontmatter. +- Changing any contents of any executable Julia cells, including cell options. + +Changes that do not invalidate a cache: + +- Editing markdown content outside of executable Julia cells. + +Caches are saved to file in a `.cache` directory alongside the notebook file. +This directory is safe to remove if you want to invalidate all caches. The +contents of the individual cache files is an internal implementation detail and +should not be relied upon. + +These caches are safe to save in CI via such tools as GitHub Actions +`action/cache` to help improve the render time of long-running notebooks that +do not often change. + +### R and Python support + +`{{r}}` and `{{python}}` executable code blocks are supported in the `julia` +engine via integrations with the +[RCall](https://github.com/JuliaInterop/RCall.jl) and +[PythonCall](https://github.com/JuliaPy/PythonCall.jl) packages respectively. +Using this feature requires the notebook author to explicitly `import` those +packages into their notebooks in a `{{julia}}` cell afterwhich they can use +`{{r}}` and `{{python}}` cells. + +````markdown +--- +title: "Multi-language notebooks" +engine: julia +--- + +```{{julia}} +import PythonCall +import RCall +``` + +Create some data in Julia: + +```{{julia}} +data = sin.(0:0.1:4pi) +``` + +Then plot it in R by interpolating the `data` variable from Julia into `R` via +the `$` syntax: + +```{{r}} +plot($data) +``` + +The same `$` syntax can be used to interpolate Julia variables into Python code as well: + +```{{python}} +len($data) +``` +```` + +### Engine "extensions" + +The implementation of `QuartoNotebookRunner` allows for extending the behaviour +of notebooks via external Julia packages. + +One example of this is the +[QuartoTools.jl](https://pumasai.github.io/QuartoTools.jl) package, which +enables fine-grained function call caching, support for serializing data +between notebook processes and normal `julia` processes, and "expandable" cell +outputs that allow for programatic creating of cell inputs and outputs within +notebooks. See the linked documentation for more thorough discussion of that +package's features. + +The same approach used by that package can be applied to other third-party +packages that wish to extend the functionality of notebooks in other ways. +Please direct questions and requests regarding this functionality to the +[QuartoNotebookRunner](https://github.com/PumasAI/QuartoNotebookRunner.jl) +repository. + ### Limitations Currently, the `engine: julia` option must be specified in each `.qmd` file. Setting the engine project-wide via `_quarto.yml` [is not yet supported](https://github.com/quarto-dev/quarto-cli/issues/3157). diff --git a/docs/prerelease/1.7/_highlights.qmd b/docs/prerelease/1.7/_highlights.qmd index 7471e9fcff..c9394b33cb 100644 --- a/docs/prerelease/1.7/_highlights.qmd +++ b/docs/prerelease/1.7/_highlights.qmd @@ -1 +1,8 @@ -You can view (in-progress) documentation for the next version of Quarto, v1.7, on our pre-release documentation site, [prerelease.quarto.org](https://prerelease.quarto.org), including a list of [highlights](https://prerelease.quarto.org/docs/prerelease/1.7/). \ No newline at end of file +Quarto 1.7 includes the following new features: + +- Improvements to the `julia` engine: + - [`juliaup` integration](/docs/computations/julia.qmd#juliaup-integration): Use specific versions of Julia in your notebooks. + - [R and Python support](/docs/computations/julia.qmd#r-and-python-support): Include `{r}` and `{python}` executable code cells via the RCall and PythonCall packages. + - [Caching](/docs/computations/julia.qmd#caching-julia): Save time rendering long-running notebooks by caching results. + - [Revise.jl integration](/docs/computations/julia.qmd#revise.jl-integration): Automatically update function definitions in Julia sessions. + diff --git a/docs/projects/code-execution.qmd b/docs/projects/code-execution.qmd index f7fac8b3f8..ceaae63f49 100644 --- a/docs/projects/code-execution.qmd +++ b/docs/projects/code-execution.qmd @@ -68,7 +68,7 @@ This sub-directory render won't use the cached `freeze` results but instead will ## Cache -You can use the `cache` option to cache the results of computations (using the [knitr cache](https://yihui.org/knitr/demo/cache/) for R documents, and [Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/) for Jupyter documents): +You can use the `cache` option to cache the results of computations (using the [knitr cache](https://yihui.org/knitr/demo/cache/) for R documents, [Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/) for Jupyter documents, or [`engine: julia`'s](../computations/julia.qmd#caching-1) built-in support): ``` yaml execute: