JupyterLab

개요

Quarto는 일반 텍스트(.qmd)로 표현된 Jupyter 노트북이나 일반 노트북 파일(.ipynb)을 렌더링할 수 있습니다. .ipynb를 사용하는 장점 중 하나는 JupyterLab을 편집기로 사용할 수 있다는 점입니다.

다음은 홈페이지의 “Hello, Quarto” 예제를 JupyterLab에서 본 모습입니다:

위에서 아래로 YAML 프론트매터, 섹션 제목, 코드 블록, 코드 블록 출력이 있는 Jupyter 노트북. 내용은 이 웹사이트 'Welcome' 페이지의 첫 부분과 동일합니다.

소스 코드를 보면 YAML 옵션이 문서 상단과 코드 셀 내부 모두에 제공되어 있음을 알 수 있습니다. YAML 옵션 작업에 대해서는 아래에서 더 자세히 설명합니다.

워크플로

JupyterLab에서 Quarto 노트북을 작성할 때의 이상적인 워크플로는 터미널에서 quarto preview 명령을 실행하는 것입니다:

Terminal
quarto preview notebook.ipynb

노트북이 렌더링되고 “라이브 미리보기”가 표시된 웹 브라우저가 열립니다. 노트북을 편집하고 저장하는 동안 볼 수 있도록 브라우저를 배치하세요:

두 개의 웹 브라우저 창이 나란히 배치되어 있습니다. 왼쪽 창은 JupyterLab 창입니다. 이 Jupyter 문서의 내용이 오른쪽 창에서 Quarto에 의해 렌더링되어 표시됩니다.

JupyterLab에서 저장할 때마다 미리보기가 자동으로 업데이트됩니다. quarto preview는 HTML과 PDF 출력 모두에 사용할 수 있습니다.

위 스크린샷에서는 JupyterLab 터미널 창 안에서 quarto preview를 실행한 것을 볼 수 있는데, 이는 렌더링 시 진행 상황과 오류 메시지를 확인할 수 있어 일반적으로 권장됩니다.

미리보기는 문서에 지정된 기본 형식을 사용합니다. 다른 형식을 사용하려면 quarto preview에 --to 옵션을 전달하세요. 예:

Terminal
quarto preview notebook.ipynb --to pdf

책이나 웹사이트를 작성 중이라면 프로젝트 디렉터리에서 quarto preview를 실행해 전체 프로젝트의 라이브 미리보기를 만들 수도 있습니다.

JupyterLab 실행

JupyterLab을 실행하려면 Quarto를 사용하는 셸에서 jupyter 모듈을 호출하세요:

플랫폼 명령
Mac/Linux 
Terminal
python3 -m jupyter lab
Windows 
Terminal
py -m jupyter lab

미리보기 없이 렌더링

quarto render 명령을 사용하면 미리보기 없이 노트북(또는 노트북 모음)을 렌더링할 수 있습니다:

Terminal
quarto render notebook.ipynb

특정 형식으로 렌더링하려면 --to 인자를 사용하세요:

Terminal
quarto render notebook.ipynb --to docx

대상 파일(이 예에서는 notebook.ipynb)은 항상 첫 번째 명령줄 인자여야 합니다.

JupyterLab 확장

Quarto JupyterLab 확장은 Quarto 마크다운을 사용하는 JupyterLab 노트북에서 마크다운 셀의 내용을 올바르게 표시할 수 있게 해줍니다. 예를 들어 Quarto JupyterLab 확장을 설치하면 노트북에서 콜아웃, Div, Mermaid 차트 등의 요소는 물론 다른 Quarto 요소(문서 프론트매터를 제목 블록으로 표시하는 기능 포함)의 렌더링 미리보기가 표시됩니다.

확장 설치에 대한 자세한 내용은 Quarto JupyterLab Extension 문서를 참고하세요.

YAML 프론트 매터

노트북의 첫 번째 셀은 문서 제목, 작성자, 그리고 기타 필요한 옵션을 포함하는 Raw 셀이어야 합니다. 노트북 도구 모음을 사용해 셀의 타입을 Raw로 변경할 수 있습니다:

JupyterLab 문서의 상단 부분. YAML 프론트매터가 들어 있는 Raw 셀이 있습니다.

이 예에서는 기본적으로 코드가 접힌 상태로 표시되도록 지정했습니다. 문서 렌더링의 다양한 측면을 제어하는 YAML 옵션이 더 있습니다. 자세한 내용은 Authoring과 Output Formats 문서를 참고하세요.

마크다운 셀

마크다운 셀의 기본 코드는 다음과 같습니다:

마크다운 셀을 포함한 JupyterLab 문서의 일부. 셀에는 마크다운으로 작성된 텍스트가 있습니다.

마크다운에 Quarto 상호 참조(@fig-polar)가 포함되어 있는 것을 확인할 수 있습니다. 마크다운 셀에는 유효한 Pandoc 마크다운 문법을 사용할 수 있습니다.

출력 옵션

Quarto는 특수 접두사(#|)가 있는 선행 주석으로 셀 옵션을 표시합니다. 여기서는 셀에서 생성된 플롯을 상호 참조할 수 있도록 label과 fig-cap 옵션을 지정했습니다.

코드 셀을 포함한 JupyterLab 문서의 일부. 코드 위쪽에 Quarto 청크 옵션 '#| label: fig-polar'와 '#| fig-cap: A line plot on a polar axis.'가 있습니다.

옵션은 셀 맨 처음에 있어야 합니다. 문서 프론트매터와 마찬가지로 옵션 이름/값에는 YAML 구문을 사용합니다.

코드, 경고, 출력 등을 선택적으로 숨길 수 있는 다양한 출력 옵션이 있습니다. 자세한 내용은 Output Options 문서를 참고하세요.

셀 실행

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정합니다). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal
quarto render notebook.ipynb --execute

노트북 YAML front matter에서 이 동작을 지정할 수도 있습니다.

notebook.ipynb
---
title: "My Notebook"
execute: 
  enabled: true
---

캐싱 제어, 커널 시작 시간 최적화 등 다양한 실행 옵션이 있습니다. 자세한 내용은 Execution Options를 참고하세요.

일반 텍스트 편집

Jupyter 노트북을 일반 텍스트 마크다운 형식으로 편집하는 것도 가능합니다. 노트북에 코드보다 설명이 더 많거나, 버전 관리에 더 적합한 파일 형식을 사용하고 싶을 때 유용합니다.

다음은 앞의 예제에서 사용한 노트북의 일반 텍스트 마크다운 버전입니다:

---
title: "Matplotlib Demo"
author: "Norah Smith"
date: "5/22/2021"
format: 
  html:
    code-fold: true
jupyter: python3
---

## 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()
```

YAML 프론트매터에 jupyter: python3 옵션을 추가해 어떤 Jupyter 커널로 렌더링할지 지정했습니다. 이 문서는 다음과 같이 렌더링합니다:

Terminal
quarto render basics-jupyter.qmd

임베디드 코드 청크가 있는 마크다운 파일은 .qmd 확장자를 사용해야 합니다.

Tip

대부분의 작업을 .qmd 파일에서 하고 있다면, Python과 Jupyter를 사용하는 .qmd 파일 편집(코드 완성, 셀 단위 실행, 나란히 미리보기 포함)을 완벽히 지원하는 RStudio를 사용하는 것을 고려해 보세요. 자세한 내용은 RStudio 사용 문서를 참고하세요.

노트북 변환

quarto convert 명령을 사용하면 노트북의 .ipynb와 .qmd 표현을 상호 변환할 수 있습니다. 예:

Terminal
quarto convert basics-jupyter.ipynb # converts to qmd
quarto convert basics-jupyter.qmd   # converts to ipynb

노트북 변환에 대한 자세한 내용은 quarto convert help를 참고하세요.

Jupytext

Jupytext를 사용하면 .qmd와 .ipynb 파일의 동기화된 병렬 버전을 유지할 수 있습니다. Jupytext에 대해 자세히 알아보려면 https://jupytext.readthedocs.io/en/latest/를 참고하세요.