diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index d6fa25def..f1ae1ef76 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 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 diff --git a/docs/advanced/quarto-execute-info.qmd b/docs/advanced/quarto-execute-info.qmd new file mode 100644 index 000000000..6ee768a23 --- /dev/null +++ b/docs/advanced/quarto-execute-info.qmd @@ -0,0 +1,222 @@ +--- +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 +info$`document-path` + +# Access format information +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 | + +### 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) + +base_format = info["format"]["identifier"]["base-format"] + +if base_format == "html": + # Use interactive visualization + import plotly.express as px + fig = px.scatter(df, x="x", y="y") + fig.show() +else: + # 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() +```