From a41858c996fa9f110b7153febd63a2b6deff4039 Mon Sep 17 00:00:00 2001
From: J S <49557684+svilupp@users.noreply.github.com>
Date: Sat, 20 Apr 2024 18:07:09 +0100
Subject: [PATCH] Added references to the QuartoNotebookRunner + example

---
 docs/src/outputformats.md | 16 +++++++++++--
 examples/quarto_report.jl | 49 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100644 examples/quarto_report.jl

diff --git a/docs/src/outputformats.md b/docs/src/outputformats.md
index 8333a3b..6f2e1a1 100644
--- a/docs/src/outputformats.md
+++ b/docs/src/outputformats.md
@@ -103,6 +103,12 @@ which can extend the range of output formats from your Literate.jl-formatted scr
 Literate.jl will produce a `.qmd` file, which can be used as input to Quarto CLI to produce
 a variety of output formats, including HTML, PDF, Word and RevealJS slides.
 
+Once you convert your Julia scripts into QMD files with Literate, you have two options for running them. You choose between them via the YAML header.
+
+1. Use Jupyter + IJulia (the default option, which can cause complications because of Python dependencies). Set `jupyter: julia-1.10` in the YAML header, where `julia-1.10` is the name of your IJulia kernel.
+2. Use the new Julia-native [QuartoNotebookRunner](https://github.com/PumasAI/QuartoNotebookRunner.jl/). Set `engine: julia` in the YAML header.
+
+
 ##### Literate + Quarto syntax tips
 
 - `# `(hashtag followed by a space) at the beginning of a line will be stripped and anything
@@ -115,12 +121,12 @@ a variety of output formats, including HTML, PDF, Word and RevealJS slides.
   rendered as `#| echo: false` and would tell Quarto not to "echo" the outputs of the
   execution (see [Guide: Executions
   options](https://quarto.org/docs/computations/execution-options.html) for more commands).
-- Make sure to always provide the YAML header and specify IJulia kernel when executing the
+- Make sure to always provide the YAML header and specify which jupyter kernel or engine to use when executing the
   file by Quarto, e.g.,
   ```
   # ---
   # title: "My Report"
-  # jupyter: julia-1.9
+  # engine: julia
   # ---
   ```
   Notice how all lines are escaped with a `# ` so Literate.jl knows to strip the hashtags
@@ -131,6 +137,10 @@ a variety of output formats, including HTML, PDF, Word and RevealJS slides.
   outputs, make sure they are surrounded by empty lines (e.g., add an empty line before and
   after the header) to help Quarto parse them correctly
 
+!!! warning "Quarto CLI Pre-Release Required"
+    The above snippet uses the Julia-native engine with QuartoNotebookRunner, which requires the pre-release version of [Quarto CLI 1.5.29](https://github.com/quarto-dev/quarto-cli/releases/tag/v1.5.29) or later.
+    If you cannot use latest Quarto CLI release, you can use the Jupyter + IJulia engine instead, by setting `jupyter: julia-1.10` in the YAML header, where `julia-1.10` is the name of your IJulia kernel.
+
 ##### Configuring Quarto for Julia code execution
 
 - Install [Quarto CLI](https://quarto.org/docs/getting-started/installation.html)
@@ -151,6 +161,8 @@ a variety of output formats, including HTML, PDF, Word and RevealJS slides.
   quarto render my_script.qmd --to html
   ```
 
+See `examples/quarto_report.jl` for an example of a Literate.jl script that can be converted to a Quarto report. 
+For more Quarto examples, visit the [QuartoNotebookRunner Examples](https://github.com/PumasAI/QuartoNotebookRunner.jl/tree/main/test/examples).
 
 ## [**4.2.** Notebook output](@id Notebook-output)
 
diff --git a/examples/quarto_report.jl b/examples/quarto_report.jl
new file mode 100644
index 0000000..3a37385
--- /dev/null
+++ b/examples/quarto_report.jl
@@ -0,0 +1,49 @@
+# ---
+# title: "Quarto Report Demo"
+# author: "Zoro"
+# date: "1/1/1900"
+# format:
+#   html:
+#     code-fold: true
+# engine: julia
+# ---
+
+# # Header 1
+# For reproducibility, we first activate the project environment and add the necessary packages
+# In practice, you can re-use your project environment - see examples with julia.exeflags
+using Pkg; Pkg.activate(".", io=devnull)
+Pkg.add(["DataFrames", "StatsPlots"])
+using DataFrames, StatsPlots
+
+# # Header 2
+# I am a text
+
+# There is a plot:
+df = DataFrame(a=1:10, b=10 .* rand(10), c=10 .* rand(10))
+@df df plot(:a, [:b :c], colour=[:red :blue])
+
+# ## Sub-header
+
+# I am a text explaining the second plot:
+@df df scatter(:a, :b, markersize=4 .* log.(:c .+ 0.1))
+
+# # Header 3
+
+# Example of mixing markdown and code
+##|echo: false
+## We could suppress printing the number by adding semicolon, but echo: false is a quarto way to hide outputs
+my_number=5
+
+# Output cell:
+##| output: asis
+println("I will be formatted as a markdown. My number is: $my_number")
+
+# The following lines will be removed from the report
+# They show you how to execute this report
+## This is how you convert this report into an HTML file #src
+using Literate #src
+Literate.markdown("quarto_report.jl", flavor = Literate.QuartoFlavor()) #src
+## The open your commandline and run the following command: #src
+## quarto render quarto_report.qmd --to html #src
+## or #src
+run(`quarto render quarto_report.qmd --to html`) #src