Skip to content

Commit 1d33734

Browse files
cscheidcwickham
cscheid
and
cwickham
authored
QUARTO_EXECUTE_INFO documentation (#1797)
* QUARTO_EXECUTE_INFO documentation * remove some lines * Update docs/advanced/quarto-execute-info.qmd Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co> * Update docs/advanced/environment-vars.qmd Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co> * Update docs/advanced/quarto-execute-info.qmd Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co> * change to base_format, use fallthrough * add link to table content --------- Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co>
1 parent 3a1354e commit 1d33734

File tree

2 files changed

+227
-1
lines changed

2 files changed

+227
-1
lines changed

‎docs/advanced/environment-vars.qmd‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,4 +86,8 @@ ENV["QUARTO_DOCUMENT_PATH"]
8686
| `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata |
8787
+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
8888
| `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. |
89-
+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
89+
+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
90+
| `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. |
91+
+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
92+
93+
For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd).

‎docs/advanced/quarto-execute-info.qmd‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
title: "Execution Context Information"
3+
summary: Access execution context metadata via QUARTO_EXECUTE_INFO
4+
format: html
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
## Accessing Execution Information
12+
13+
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.
14+
15+
::: panel-tabset
16+
## Python
17+
18+
``` python
19+
import os
20+
import json
21+
22+
with open(os.environ["QUARTO_EXECUTE_INFO"]) as f:
23+
info = json.load(f)
24+
25+
# Access document path
26+
print(info["document-path"])
27+
28+
# Access format information
29+
print(info["format"]["identifier"]["target-format"])
30+
```
31+
32+
## R
33+
34+
``` r
35+
library(jsonlite)
36+
37+
info_file <- Sys.getenv("QUARTO_EXECUTE_INFO")
38+
info <- fromJSON(info_file)
39+
40+
# Access document path
41+
info$`document-path`
42+
43+
# Access format information
44+
info$format$identifier$`target-format`
45+
```
46+
47+
## Julia
48+
49+
``` julia
50+
using JSON
51+
52+
info = JSON.parsefile(ENV["QUARTO_EXECUTE_INFO"])
53+
54+
# Access document path
55+
println(info["document-path"])
56+
57+
# Access format information
58+
println(info["format"]["identifier"]["target-format"])
59+
```
60+
:::
61+
62+
## JSON Structure
63+
64+
The JSON object contains the following top-level fields:
65+
66+
| Field | Type | Description |
67+
|-------|------|-------------|
68+
| `document-path` | string | Absolute path to the source document being rendered |
69+
| `format` | object | Complete format configuration including execution, rendering, and pandoc settings |
70+
71+
### Format Object
72+
73+
The `format` object contains comprehensive configuration information organized into several sections:
74+
75+
| Field | Type | Description |
76+
|-------|------|-------------|
77+
| `identifier` | object | Format identification including `display-name`, `target-format`, and `base-format` |
78+
| `execute` | object | Execution options such as `fig-width`, `fig-height`, `echo`, `eval`, `warning`, etc. |
79+
| `render` | object | Rendering options including `keep-tex`, `code-fold`, `fig-align`, output extensions, etc. |
80+
| `pandoc` | object | Pandoc-specific settings like `standalone`, `to`, and `default-image-extension` |
81+
| `language` | object | Localized text for UI elements, section titles, callouts, and other interface strings |
82+
| `metadata` | object | Document metadata including title and format-specific options |
83+
84+
### Format Identifier
85+
86+
The `identifier` object provides format classification:
87+
88+
| Field | Type | Description |
89+
|-------|------|-------------|
90+
| `display-name` | string | Human-readable format name (e.g., "Github (GFM)", "HTML") |
91+
| `target-format` | string | The target output format identifier (e.g., "gfm", "html") |
92+
| `base-format` | string | The base format that the target inherits from |
93+
94+
### Execute Options
95+
96+
The `execute` object contains code execution settings. Common fields include:
97+
98+
| Field | Type | Description |
99+
|-------|------|-------------|
100+
| `eval` | boolean | Whether to evaluate code cells |
101+
| `echo` | boolean | Whether to include code in output |
102+
| `output` | boolean | Whether to include code output |
103+
| `warning` | boolean | Whether to include warnings |
104+
| `error` | boolean | Whether to include errors |
105+
| `include` | boolean | Whether to include the cell in the output |
106+
| `cache` | boolean \| null | Whether to cache execution results |
107+
| `freeze` | boolean | Whether to freeze execution |
108+
| `fig-width` | number | Default figure width in inches |
109+
| `fig-height` | number | Default figure height in inches |
110+
| `fig-format` | string | Default figure format (e.g., "png", "svg") |
111+
| `fig-dpi` | number | Default figure DPI resolution |
112+
113+
### Render Options
114+
115+
The `render` object contains rendering configuration. Common fields include:
116+
117+
| Field | Type | Description |
118+
|-------|------|-------------|
119+
| `keep-tex` | boolean | Whether to keep intermediate TeX files |
120+
| `keep-typ` | boolean | Whether to keep intermediate Typst files |
121+
| `keep-source` | boolean | Whether to keep source files |
122+
| `output-ext` | string | Output file extension (e.g., "md", "html") |
123+
| `fig-align` | string | Default figure alignment |
124+
125+
### Pandoc Options
126+
127+
The `pandoc` object contains pandoc-specific settings:
128+
129+
| Field | Type | Description |
130+
|-------|------|-------------|
131+
| `to` | string | Pandoc output format |
132+
| `standalone` | boolean | Whether to produce standalone output |
133+
| `default-image-extension` | string | Default file extension for images |
134+
135+
## Use Cases
136+
137+
### Conditional Execution Based on Format
138+
139+
You can adapt your code's behavior based on the output format:
140+
141+
::: panel-tabset
142+
## Python
143+
144+
``` python
145+
import os
146+
import json
147+
148+
with open(os.environ["QUARTO_EXECUTE_INFO"]) as f:
149+
info = json.load(f)
150+
151+
base_format = info["format"]["identifier"]["base-format"]
152+
153+
if base_format == "html":
154+
# Use interactive visualization
155+
import plotly.express as px
156+
fig = px.scatter(df, x="x", y="y")
157+
fig.show()
158+
else:
159+
# Use static plot
160+
import matplotlib.pyplot as plt
161+
plt.scatter(df["x"], df["y"])
162+
plt.show()
163+
```
164+
165+
## R
166+
167+
``` r
168+
library(jsonlite)
169+
170+
info <- fromJSON(Sys.getenv("QUARTO_EXECUTE_INFO"))
171+
target_format <- info$format$identifier$`target-format`
172+
173+
if (target_format == "html") {
174+
# Use interactive visualization
175+
library(plotly)
176+
plot_ly(df, x = ~x, y = ~y, type = "scatter")
177+
} else if (target_format %in% c("pdf", "latex")) {
178+
# Use static plot
179+
plot(df$x, df$y)
180+
}
181+
```
182+
:::
183+
184+
### Format-Aware Resource Paths
185+
186+
Access the document path to construct relative paths to resources:
187+
188+
``` python
189+
import os
190+
import json
191+
from pathlib import Path
192+
193+
with open(os.environ["QUARTO_EXECUTE_INFO"]) as f:
194+
info = json.load(f)
195+
196+
doc_path = Path(info["document-path"])
197+
doc_dir = doc_path.parent
198+
199+
# Load data relative to document
200+
data_file = doc_dir / "data" / "input.csv"
201+
```
202+
203+
### Adapting Output Based on Figure Settings
204+
205+
Use execution settings to adapt visualization parameters:
206+
207+
``` python
208+
import os
209+
import json
210+
import matplotlib.pyplot as plt
211+
212+
with open(os.environ["QUARTO_EXECUTE_INFO"]) as f:
213+
info = json.load(f)
214+
215+
fig_width = info["format"]["execute"]["fig-width"]
216+
fig_height = info["format"]["execute"]["fig-height"]
217+
fig_dpi = info["format"]["execute"]["fig-dpi"]
218+
219+
plt.figure(figsize=(fig_width, fig_height), dpi=fig_dpi)
220+
plt.plot(x, y)
221+
plt.show()
222+
```

0 commit comments

Comments
 (0)