튜토리얼: 안녕, Quarto

도구 선택

개요

이 튜토리얼에서는 Jupyter Lab에서 Quarto를 사용하는 방법을 보여드립니다. 일반적인 노트북처럼 Jupyter Lab에서 코드와 마크다운을 편집하고, 작업하면서 렌더링된 문서를 웹 브라우저에서 미리보게 됩니다.

아래는 전체 흐름의 개요입니다.

왼쪽: Quarto Basics라는 제목의 Jupyter 노트북에 텍스트, 코드 셀, 그리고 코드 셀 결과(극좌표 축의 선 그래프)가 보입니다. 오른쪽: 같은 노트북의 렌더링 버전.

왼쪽의 노트북이 오른쪽에 보이는 HTML 버전으로 렌더링됩니다. 이것이 Quarto 배포의 기본 모델입니다. 즉, 소스 문서(여기서는 노트북)를 가져와 HTML, PDF, MS Word 등 다양한 출력 형식으로 렌더링합니다.

Note

이 튜토리얼은 Python을 사용하지만, Julia(IJulia 커널을 통해)도 잘 지원됩니다. 자세한 내용은 Julia 사용하기 문서를 참고하세요.

렌더링

Jupyter Lab에서 노트북(hello.ipynb)을 열고 여러 형식으로 렌더링하는 것부터 시작하겠습니다. 자신의 환경에서 단계별로 따라 하려면 아래 노트북을 다운로드하세요.

Download hello.ipynb

그런 다음 새 작업 디렉터리를 만들고 노트북을 해당 디렉터리로 복사한 뒤 터미널에서 해당 디렉터리로 이동하세요.

다음 명령을 실행해 JupyterLab과 튜토리얼에 사용하는 패키지(matplotlib, plotly)를 설치하고 튜토리얼 노트북을 여세요.

Platform Commands

Mac/Linux

Platform	Commands
Mac/Linux	Terminal `python3 -m pip install jupyter jupyterlab python3 -m pip install matplotlib plotly python3 -m jupyter lab hello.ipynb`
Windows	Terminal `py -m pip install jupyter jupyterlab py -m pip install matplotlib plotly py -m jupyter lab hello.ipynb`

Terminal

python3 -m pip install jupyter jupyterlab
python3 -m pip install matplotlib plotly
python3 -m jupyter lab hello.ipynb

Windows

Terminal

py -m pip install jupyter jupyterlab
py -m pip install matplotlib plotly
py -m jupyter lab hello.ipynb

Jupyter Lab에서 노트북은 아래처럼 보입니다.

---
title: "Quarto Basics"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

Quarto Basics라는 제목의 Jupyter 노트북에 텍스트, 코드 셀, 그리고 코드 셀 결과(극좌표 축의 선 그래프)가 보입니다.

다음으로 Jupyter Lab에서 Quarto 명령을 실행할 새 터미널을 만드세요.

Jupyter Lab 메뉴 항목 스크린샷: File > New > Terminal.

마지막으로 노트북을 몇 가지 형식으로 렌더링합니다.

Terminal

quarto render hello.ipynb --to html
quarto render hello.ipynb --to docx

대상 파일(이 경우 hello.ipynb)은 항상 명령줄 인자의 첫 번째에 있어야 합니다.

Quarto로 Jupyter 노트북을 렌더링하면 노트북의 내용(코드, 마크다운, 출력)이 일반 마크다운으로 변환된 뒤 Pandoc에서 처리되어 최종 형식이 생성됩니다.

Jupyter 노트북 -> md -> pandoc -> PDF/MS Word/HTML로 이어지는 워크플로 다이어그램.

저작

quarto render 명령은 배포용 문서의 최종 버전을 만드는 데 사용됩니다. 하지만 저작 단계에서는 quarto preview 명령을 사용합니다. 지금 터미널에서 hello.ipynb로 실행해 보세요.

Terminal

quarto preview hello.ipynb

이 명령은 문서를 렌더링한 다음 웹 브라우저에 표시합니다.

이전 노트북을 웹 브라우저에서 렌더링한 모습.

변경 사항을 보면서 작업할 수 있도록 Jupyter Lab과 브라우저 미리보기를 나란히 배치하는 것이 좋습니다.

왼쪽에 노트북, 오른쪽에 브라우저의 라이브 미리보기가 나란히 표시된 모습.

라이브 미리보기를 확인해 보겠습니다.

theta를 정의하는 코드를 다음과 같이 변경하세요.
```
theta = 4 * np.pi * r
```
코드 셀을 다시 실행하여 새 플롯을 생성합니다.
노트북을 저장합니다(미리보기가 자동으로 업데이트됩니다).

이것이 Quarto 저작의 기본 워크플로입니다. 익숙해지면 JupyterLab에서 Quarto 작업을 위한 추가 도구를 제공하는 Quarto JupyterLab 확장 설치도 권장합니다.

노트북에는 여러 종류의 셀이 있으니 각각을 조금씩 살펴보겠습니다.

YAML 옵션

마크다운과 코드 셀은 익숙하겠지만, 문서 수준의 YAML 옵션에 사용되는 새로운 셀 유형(“Raw”)이 있습니다.

---
title: "Quarto Basics"
format:
  html:
    code-fold: true
jupyter: python3
---

노트북의 YAML. title, format, jupyter 필드가 있으며, title은 Quarto Basics, format은 html, 그 아래에 code-fold가 true로 설정되어 있습니다. jupyter는 python3으로 설정되어 있습니다.

code-fold 옵션을 false로 바꿔 보세요.

format: 
  html:
    code-fold: false

그 다음 노트북을 저장하세요. 이제 플롯 위에 코드가 표시될 것입니다. 이전에는 Code 버튼으로 숨겨져 있었습니다.

마크다운 셀

마크다운 셀에는 렌더링 시 Quarto로 전달될 원시 마크다운이 들어 있습니다. 이 셀에서는 어떤 유효한 Quarto 마크다운 문법도 사용할 수 있습니다. 여기서는 제목과 아래 코드 셀에서 생성된 그림에 대한 상호 참조를 지정합니다.

## Polar Axis

For a demonstration of a line plot on a polar axis, see @fig-polar.

두 번째 수준 제목 Polar Axis와 'For a demonstration of a line plot on a polar axis, see @fig-polar.'라는 텍스트가 있는 마크다운 셀.

제목을 변경한 뒤 노트북을 저장해 보세요. 미리보기의 제목 텍스트가 업데이트됩니다.

코드 셀

아래와 같은 코드 셀은 이미 익숙하실 겁니다.

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

label과 fig-cap 옵션이 있는 코드 셀과 극좌표 축의 선 그래프를 만드는 코드.

하지만 코드 셀 상단에 새로운 구성 요소가 있습니다. label과 fig-cap 옵션입니다. 셀 옵션은 특수 접두사가 붙은 주석(#|)으로 YAML 형식으로 작성합니다.

이 예제에서는 셀 옵션을 사용해 그림을 상호 참조할 수 있도록 했습니다. fig-cap과/또는 코드를 변경하고 셀을 실행한 다음 노트북을 저장해 업데이트된 미리보기를 확인해 보세요.

출력을 원하는 방식으로 조정할 수 있는 다양한 셀 옵션이 있습니다. 이 옵션들은 다음 튜토리얼에서 더 자세히 다룹니다.

Note

그림에서 특히 유용한 셀 옵션 중 하나는 fig-alt입니다. 시각 장애가 있는 사용자를 위해 이미지에 대체 텍스트를 추가할 수 있습니다. 자세한 내용은 Amy Cesal의 데이터 시각화를 위한 대체 텍스트 작성하기 글을 참고하세요.

다음 단계

이제 Quarto 문서를 만들고 작성하는 기본을 익혔습니다. 다음 튜토리얼에서 Quarto를 더 깊이 있게 살펴보세요:

튜토리얼: 계산 — 실행 가능한 코드 블록의 동작과 출력을 원하는 방식으로 조정하는 방법을 배웁니다.
튜토리얼: 작성 — 출력 형식과 인용, 상호 참조, 고급 레이아웃 같은 기술 문서 작성 기능을 더 알아봅니다.

또한 JupyterLab에서 Quarto 작업을 위한 추가 도구를 제공하는 Quarto JupyterLab 확장 설치도 고려해 보세요.