스크립트 파일 렌더링

개요

Quarto는 노트북 형식으로 특별히 포맷된 스크립트 파일(예: .py, .jl, .r) 렌더링을 지원합니다. 이 형식의 구문은 Jupyter와 Knitr 엔진에서 다릅니다. Jupyter 엔진은 Python, Julia, R( IRkernel 사용) 스크립트를 렌더링할 수 있고, Knitr 엔진은 R 스크립트만 렌더링합니다.

이 페이지에서는 Jupyter와 Knitr 노트북 스크립트의 문법, 노트북 스크립트 렌더링과 미리보기, 그리고 프로젝트에서 노트북 스크립트를 사용하는 방법을 소개합니다.

문법

YAML, 코드, 마크다운을 구분하는 문법은 Jupyter 또는 Knitr 엔진 중 어떤 것으로 렌더링하느냐에 따라 달라집니다. Python과 Julia 스크립트는 Jupyter 엔진을 사용합니다. R 스크립트는 Jupyter 또는 Knitr 엔진 중 어느 쪽이든 사용할 수 있습니다.

Jupyter

Jupyter용 스크립트 렌더링은 Spyder, VS Code, PyCharm, Jupytext 등 여러 도구가 지원하는 퍼센트 포맷을 사용합니다.

퍼센트 포맷에서는:

마크다운 셀은 # %% [markdown]으로 구분하며, 한 줄 주석(#) 또는 여러 줄 문자열(""")로 내용을 포함할 수 있습니다.
코드 셀은 # %%로 구분합니다.

Quarto 전용 추가 규칙은 다음과 같습니다.

스크립트는 YAML 헤더 블록(일반적인 --- YAML 구분자 포함)이 들어 있는 마크다운 셀로 시작해야 합니다.
#| 주석으로 코드 셀 옵션을 추가할 수 있습니다.

예를 들어 아래는 마크다운과 코드 셀을 모두 포함하는 Python 스크립트입니다(오른쪽의 번호를 클릭하면 자세한 설명을 볼 수 있습니다).

script.py

# %% [markdown]
# ---
# title: Palmer Penguins
# author: Norah Jones
# date: 3/12/23
# ---

# %%
#| echo: false
import pandas as pd
df = pd.read_csv("palmer-penguins.csv")

# %% [markdown]
"""
## Exploring the data

See @fig-bill-sizes for an exploration of bill sizes by species.
"""

# %% 
#| label: fig-bill-sizes
#| fig-cap: Bill Sizes by Species
                                          
import matplotlib.pyplot as plt           
import seaborn as sns

g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5)
g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend()

1: Quarto로 렌더링되는 스크립트는 YAML 헤더가 포함된 마크다운 셀로 시작해야 합니다.
2: 코드 셀입니다.
3: 여러 줄 문자열(""")을 포함한 마크다운 셀입니다.
4: #| 주석으로 코드 셀 옵션을 지정합니다.
5: 셀 안에 빈 줄을 포함할 수 있습니다(다음 셀을 만나기 전까지 동일 셀로 간주됩니다).

마크다운 생성

Jupyter 스크립트는 문서 대부분이 마크다운을 동적으로 생성하는 코드로 구성될 때 특히 편리합니다. IPython.display 모듈의 함수로 Python에서 마크다운을 작성할 수 있습니다. 예:

# %%
#| echo: false
radius = 10
from IPython.display import Markdown
Markdown(f"The _radius_ of the circle is **{radius}**.")

동적으로 생성된 마크다운도 Quarto의 표준 출력 div 안에 포함됩니다. Quarto의 기본 출력 래핑을 모두 제거하려면 output: asis 옵션을 사용하세요. 예:

# %%
#| echo: false
#| output: asis
radius = 10
from IPython.display import Markdown
Markdown(f"The _radius_ of the circle is **{radius}**.")

원시 셀

# %% [raw] 셀 구분자와 format 속성을 함께 사용하면 스크립트 안에 원시 셀(예: HTML 또는 LaTeX)을 포함할 수 있습니다. 예:

# %% [raw] format="html"
"""
<iframe width="560" height="315" src="https://www.youtube.com/embed/lJIrF4YjHfQ?si=aP7PxA1Pz8IIoQUX"></iframe>
"""

Knitr

Knitr 스크립트 렌더링은 knitr::spin() 기능에 기반하며, 동일한 문법 규칙을 사용합니다.

마크다운 콘텐츠는 특수 주석 #'로 시작하는 줄에 포함됩니다.
#로 시작하지 않는 줄은 코드입니다. 마크다운 콘텐츠가 나타나면 코드 블록이 분리되므로, 새로운 코드 블록을 만들려면 #'를 사용합니다.

Quarto 전용 추가 규칙은 다음과 같습니다.

R 스크립트는 #' 주석을 사용하는 YAML 헤더 블록으로 시작해야 합니다.
#| 주석으로 코드 셀 옵션을 추가할 수 있습니다.

예를 들어 아래는 마크다운과 코드 셀을 모두 포함하는 R 스크립트입니다(오른쪽의 번호를 클릭하면 자세한 설명을 볼 수 있습니다).

script.R

#' ---
#' title: Palmer Penguins
#' author: Norah Jones
#' date: 3/12/23
#' format: html
#' ---

library(palmerpenguins)

#' ## Exploring the data
#' See @fig-bill-sizes for an exploration of bill sizes by species.

#| label: fig-bill-sizes
#| fig-cap: Bill Sizes by Species
#| warning: false
library(ggplot2)
ggplot(data = penguins,
       aes(x = bill_length_mm,
           y = bill_depth_mm,
           group = species)) +
  geom_point(aes(color = species,
                 shape = species),
             size = 3,
             alpha = 0.8) +
  labs(title = "Penguin bill dimensions",
       subtitle = "Bill length and depth for Adelie, Chinstrap and Gentoo Penguins at Palmer Station LTER",
       x = "Bill length (mm)",
       y = "Bill depth (mm)",
       color = "Penguin species",
       shape = "Penguin species")

1: Quarto로 렌더링되는 스크립트는 #' 주석을 사용한 YAML 헤더로 시작해야 합니다.
2: R 코드는 R 스크립트의 주요 콘텐츠이며 별도 구분 없이 포함됩니다.
3: 마크다운 콘텐츠는 #' 주석을 앞에 붙입니다.
4: 코드 셀 옵션은 #| 주석으로 지정하며 그 아래 코드에 적용됩니다.

렌더링과 미리보기

노트북 스크립트는 .qmd 또는 .ipynb 파일과 마찬가지로 렌더링하고 미리볼 수 있습니다. 예:

$ quarto render script.py
$ quarto render script.jl
$ quarto render script.R

$ quarto preview script.py
$ quarto preview script.jl
$ quarto preview script.R

스크립트는 Quarto가 YAML 블록을 렌더링할 수 있도록 적절한 문법으로 시작해야 합니다. Quarto는 감지된 문법에 따라 Jupyter 또는 Knitr 엔진으로 렌더링합니다.

Quarto VS Code 확장도 스크립트의 렌더링 및 미리보기를 지원합니다.

프로젝트에서 스크립트 사용

노트북 스크립트는 프로젝트(예: 웹사이트, 블로그 등)에도 포함할 수 있습니다. 프로젝트 안의 스크립트는 적절한 문법으로 시작할 때만 Quarto가 렌더링합니다.

필요에 따라 특정 스크립트를 무시하려면 _quarto.yml에서 렌더 목록을 명시적으로 만들어 제외할 수 있습니다. 예:

project:
  type: website
  render:
    - "*.{qmd,R,py}"
    - "!utils.py"

이 방법은 문서의 완결성을 위해 설명하지만, 실제로는 거의 필요하지 않습니다. 보고서 렌더링을 위해 특별히 작성하지 않는 한 스크립트가 YAML 블록으로 시작하는 경우가 거의 없기 때문입니다.