From 1622399708d19a0050609eb012235d6a35d5a99c Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Wed, 8 Oct 2025 13:30:30 -0500 Subject: [PATCH 1/7] QUARTO_EXECUTE_INFO documentation --- docs/advanced/environment-vars.qmd | 6 +- docs/advanced/quarto-execute-info.qmd | 226 ++++++++++++++++++++++++++ 2 files changed, 231 insertions(+), 1 deletion(-) create mode 100644 docs/advanced/quarto-execute-info.qmd diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index d6fa25def..76e4d00a8 100644 --- a/docs/advanced/environment-vars.qmd +++ b/docs/advanced/environment-vars.qmd @@ -86,4 +86,8 @@ ENV["QUARTO_DOCUMENT_PATH"] | `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata | +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ \ No newline at end of file ++--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the name of a file containing a JSON object with execution information for Quarto engines. This is accessible by code in executable code cells. | ++--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd). \ No newline at end of file diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd new file mode 100644 index 000000000..17e630d60 --- /dev/null +++ b/docs/advanced/quarto-execute-info.qmd @@ -0,0 +1,226 @@ +--- +title: "Execution Context Information" +summary: Access execution context metadata via QUARTO_EXECUTE_INFO +format: html +--- + +## Overview + +When Quarto executes code cells in a document, it provides detailed execution context information through the `QUARTO_EXECUTE_INFO` environment variable. This variable contains the path to a JSON file with metadata about the document being rendered and the format being used. + +## Accessing Execution Information + +The `QUARTO_EXECUTE_INFO` environment variable contains a file path pointing to a JSON file with execution metadata. You can read this file in your code to access information about the current execution context. + +::: panel-tabset +## Python + +``` python +import os +import json + +with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: + info = json.load(f) + +# Access document path +print(info["document-path"]) + +# Access format information +print(info["format"]["identifier"]["target-format"]) +``` + +## R + +``` r +library(jsonlite) + +info_file <- Sys.getenv("QUARTO_EXECUTE_INFO") +info <- fromJSON(info_file) + +# Access document path +print(info$`document-path`) + +# Access format information +print(info$format$identifier$`target-format`) +``` + +## Julia + +``` julia +using JSON + +info = JSON.parsefile(ENV["QUARTO_EXECUTE_INFO"]) + +# Access document path +println(info["document-path"]) + +# Access format information +println(info["format"]["identifier"]["target-format"]) +``` +::: + +## JSON Structure + +The JSON object contains the following top-level fields: + +| Field | Type | Description | +|-------|------|-------------| +| `document-path` | string | Absolute path to the source document being rendered | +| `format` | object | Complete format configuration including execution, rendering, and pandoc settings | + +### Format Object + +The `format` object contains comprehensive configuration information organized into several sections: + +| Field | Type | Description | +|-------|------|-------------| +| `identifier` | object | Format identification including `display-name`, `target-format`, and `base-format` | +| `execute` | object | Execution options such as `fig-width`, `fig-height`, `echo`, `eval`, `warning`, etc. | +| `render` | object | Rendering options including `keep-tex`, `code-fold`, `fig-align`, output extensions, etc. | +| `pandoc` | object | Pandoc-specific settings like `standalone`, `to`, and `default-image-extension` | +| `language` | object | Localized text for UI elements, section titles, callouts, and other interface strings | +| `metadata` | object | Document metadata including title and format-specific options | + +### Format Identifier + +The `identifier` object provides format classification: + +| Field | Type | Description | +|-------|------|-------------| +| `display-name` | string | Human-readable format name (e.g., "Github (GFM)", "HTML") | +| `target-format` | string | The target output format identifier (e.g., "gfm", "html") | +| `base-format` | string | The base format that the target inherits from | + +### Execute Options + +The `execute` object contains code execution settings. Common fields include: + +| Field | Type | Description | +|-------|------|-------------| +| `eval` | boolean | Whether to evaluate code cells | +| `echo` | boolean | Whether to include code in output | +| `output` | boolean | Whether to include code output | +| `warning` | boolean | Whether to include warnings | +| `error` | boolean | Whether to include errors | +| `include` | boolean | Whether to include the cell in the output | +| `cache` | boolean \| null | Whether to cache execution results | +| `freeze` | boolean | Whether to freeze execution | +| `fig-width` | number | Default figure width in inches | +| `fig-height` | number | Default figure height in inches | +| `fig-format` | string | Default figure format (e.g., "png", "svg") | +| `fig-dpi` | number | Default figure DPI resolution | + +### Render Options + +The `render` object contains rendering configuration. Common fields include: + +| Field | Type | Description | +|-------|------|-------------| +| `keep-tex` | boolean | Whether to keep intermediate TeX files | +| `keep-typ` | boolean | Whether to keep intermediate Typst files | +| `keep-source` | boolean | Whether to keep source files | +| `output-ext` | string | Output file extension (e.g., "md", "html") | +| `fig-align` | string | Default figure alignment | +| `code-fold` | string | Code folding behavior ("none", "show", "hide") | +| `code-overflow` | string | How to handle code overflow ("scroll", "wrap") | +| `code-line-numbers` | boolean | Whether to show line numbers | +| `tbl-colwidths` | boolean | Whether to use table column widths | + +### Pandoc Options + +The `pandoc` object contains pandoc-specific settings: + +| Field | Type | Description | +|-------|------|-------------| +| `to` | string | Pandoc output format | +| `standalone` | boolean | Whether to produce standalone output | +| `default-image-extension` | string | Default file extension for images | + +## Use Cases + +### Conditional Execution Based on Format + +You can adapt your code's behavior based on the output format: + +::: panel-tabset +## Python + +``` python +import os +import json + +with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: + info = json.load(f) + +target_format = info["format"]["identifier"]["target-format"] + +if target_format == "html": + # Use interactive visualization + import plotly.express as px + fig = px.scatter(df, x="x", y="y") + fig.show() +elif target_format in ["pdf", "latex"]: + # Use static plot + import matplotlib.pyplot as plt + plt.scatter(df["x"], df["y"]) + plt.show() +``` + +## R + +``` r +library(jsonlite) + +info <- fromJSON(Sys.getenv("QUARTO_EXECUTE_INFO")) +target_format <- info$format$identifier$`target-format` + +if (target_format == "html") { + # Use interactive visualization + library(plotly) + plot_ly(df, x = ~x, y = ~y, type = "scatter") +} else if (target_format %in% c("pdf", "latex")) { + # Use static plot + plot(df$x, df$y) +} +``` +::: + +### Format-Aware Resource Paths + +Access the document path to construct relative paths to resources: + +``` python +import os +import json +from pathlib import Path + +with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: + info = json.load(f) + +doc_path = Path(info["document-path"]) +doc_dir = doc_path.parent + +# Load data relative to document +data_file = doc_dir / "data" / "input.csv" +``` + +### Adapting Output Based on Figure Settings + +Use execution settings to adapt visualization parameters: + +``` python +import os +import json +import matplotlib.pyplot as plt + +with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: + info = json.load(f) + +fig_width = info["format"]["execute"]["fig-width"] +fig_height = info["format"]["execute"]["fig-height"] +fig_dpi = info["format"]["execute"]["fig-dpi"] + +plt.figure(figsize=(fig_width, fig_height), dpi=fig_dpi) +plt.plot(x, y) +plt.show() +``` From 34241b68556eaae3d4292f386ac6ee6876190f73 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Wed, 8 Oct 2025 13:44:45 -0500 Subject: [PATCH 2/7] remove some lines --- docs/advanced/quarto-execute-info.qmd | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd index 17e630d60..de5d04efa 100644 --- a/docs/advanced/quarto-execute-info.qmd +++ b/docs/advanced/quarto-execute-info.qmd @@ -121,10 +121,6 @@ The `render` object contains rendering configuration. Common fields include: | `keep-source` | boolean | Whether to keep source files | | `output-ext` | string | Output file extension (e.g., "md", "html") | | `fig-align` | string | Default figure alignment | -| `code-fold` | string | Code folding behavior ("none", "show", "hide") | -| `code-overflow` | string | How to handle code overflow ("scroll", "wrap") | -| `code-line-numbers` | boolean | Whether to show line numbers | -| `tbl-colwidths` | boolean | Whether to use table column widths | ### Pandoc Options From b430c313c23e58670b52ce45c69d3fb5c3da10c7 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger <285675+cscheid@users.noreply.github.com> Date: Wed, 8 Oct 2025 17:31:23 -0500 Subject: [PATCH 3/7] Update docs/advanced/quarto-execute-info.qmd Co-authored-by: Charlotte Wickham --- docs/advanced/quarto-execute-info.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd index de5d04efa..c1b92d92a 100644 --- a/docs/advanced/quarto-execute-info.qmd +++ b/docs/advanced/quarto-execute-info.qmd @@ -38,7 +38,7 @@ info_file <- Sys.getenv("QUARTO_EXECUTE_INFO") info <- fromJSON(info_file) # Access document path -print(info$`document-path`) +info$`document-path` # Access format information print(info$format$identifier$`target-format`) From 2bbca82e144facf34d60ab70c5fb9da43c56fd1b Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger <285675+cscheid@users.noreply.github.com> Date: Wed, 8 Oct 2025 17:33:51 -0500 Subject: [PATCH 4/7] Update docs/advanced/environment-vars.qmd Co-authored-by: Charlotte Wickham --- docs/advanced/environment-vars.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index 76e4d00a8..125ca927c 100644 --- a/docs/advanced/environment-vars.qmd +++ b/docs/advanced/environment-vars.qmd @@ -87,7 +87,7 @@ ENV["QUARTO_DOCUMENT_PATH"] +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the name of a file containing a JSON object with execution information for Quarto engines. This is accessible by code in executable code cells. | +| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with execution information for Quarto engines. This is accessible by code in executable code cells. | +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd). \ No newline at end of file From 970ee6c6b0cf238997e8011571cef8028e940fc3 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger <285675+cscheid@users.noreply.github.com> Date: Wed, 8 Oct 2025 17:34:11 -0500 Subject: [PATCH 5/7] Update docs/advanced/quarto-execute-info.qmd Co-authored-by: Charlotte Wickham --- docs/advanced/quarto-execute-info.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd index c1b92d92a..b648ce989 100644 --- a/docs/advanced/quarto-execute-info.qmd +++ b/docs/advanced/quarto-execute-info.qmd @@ -41,7 +41,7 @@ info <- fromJSON(info_file) info$`document-path` # Access format information -print(info$format$identifier$`target-format`) +info$format$identifier$`target-format` ``` ## Julia From 12a2d96d44ebbb7cb2e7071d4f7572b0767caaf0 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Wed, 8 Oct 2025 17:44:49 -0500 Subject: [PATCH 6/7] change to base_format, use fallthrough --- docs/advanced/quarto-execute-info.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd index b648ce989..6ee768a23 100644 --- a/docs/advanced/quarto-execute-info.qmd +++ b/docs/advanced/quarto-execute-info.qmd @@ -148,14 +148,14 @@ import json with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: info = json.load(f) -target_format = info["format"]["identifier"]["target-format"] +base_format = info["format"]["identifier"]["base-format"] -if target_format == "html": +if base_format == "html": # Use interactive visualization import plotly.express as px fig = px.scatter(df, x="x", y="y") fig.show() -elif target_format in ["pdf", "latex"]: +else: # Use static plot import matplotlib.pyplot as plt plt.scatter(df["x"], df["y"]) From 6bafca5146003a505de236047767b83a24a3a179 Mon Sep 17 00:00:00 2001 From: Carlos Scheidegger Date: Thu, 9 Oct 2025 11:04:04 -0500 Subject: [PATCH 7/7] add link to table content --- docs/advanced/environment-vars.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index 125ca927c..f1ae1ef76 100644 --- a/docs/advanced/environment-vars.qmd +++ b/docs/advanced/environment-vars.qmd @@ -87,7 +87,7 @@ ENV["QUARTO_DOCUMENT_PATH"] +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with execution information for Quarto engines. This is accessible by code in executable code cells. | +| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with [execution information for Quarto engines](./quarto-execute-info.qmd). This is accessible by code in executable code cells. | +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd). \ No newline at end of file