튜토리얼: 안녕, Quarto

개요

이 튜토리얼에서는 Neovim에서 Quarto를 사용하는 방법을 보여드립니다. 여기서는 기본을 다루지만, Quarto에서 Neovim을 설치, 사용, 사용자화하는 방법을 더 알고 싶다면 Quarto에서 Neovim 사용하기 문서를 참고하세요.

이미 Neovim을 원하는 대로 구성했다면 quarto-nvim 플러그인만 추가한 뒤, 이 가이드를 영감과 가능성을 확인하는 용도로만 보셔도 좋습니다. 하지만 Neovim이 완전히 처음이거나 Quarto 데이터 사이언스용으로 이미 구성된 설정을 간단히 체험하고 싶다면, 이 kickstarter 구성으로 시작하세요. 이 튜토리얼에서도 이를 사용합니다.

Note

Neovim은 매우 사용자화 가능한 편집기입니다. 그래서 Neovim 코어 멤버인 TJ Devries는 최근 VS Code나 RStudio 같은 IDE와 구분하기 위해 Personal Development Environments(PDE)라는 용어를 만들었습니다.1

기본 상태의 Neovim은 상당히 미니멀합니다. 효율적으로 작업하고 다양한 기능을 사용하려면 구성해야 합니다. 즉, 자신만의 환경으로 만들어야 합니다. 이 접근이 매력적으로 느껴진다면 계속 읽어보세요. 토끼굴에 오신 것을 환영합니다. 🐰

이 글과 함께 kickstarter 구성을 빠르게 시작하는 방법은 이 비디오로도 확인할 수 있습니다.

Quarto Neovim 플러그인은 바퀴를 다시 발명하려 하지 않습니다. Neovim 생태계의 기존 플러그인을 활용해 전체 경험을 제공합니다. quarto-nvim이 제공하며 kickstarter 구성에 포함된 플러그인으로 강화되는 기능은 다음과 같습니다.

  • Quarto 문서 미리보기
  • 마크다운 및 임베디드 언어 구문 강조
  • 임베디드 언어(예: Python, R, Julia 등) 자동 완성
  • 셀 및 선택 영역 실행을 위한 명령과 키 바인딩
  • 참고문헌, 파일 경로, LaTeX 수식 기호, 이모지 자동 완성
  • 선택적 맞춤법 검사와 자동 완성
  • 코드 스니펫
  • 코드 청크를 독립 실행형 스크립트로 내보내기

자세한 내용은 Quarto에서 Neovim 사용하기 문서를 참고하세요.

기본 워크플로

Quarto .qmd 파일은 마크다운과 실행 가능한 코드 셀의 조합으로 구성됩니다. Neovim에서 .qmd 파일을 편집하고 미리보기하면 다음과 같은 모습입니다.

나란히 배치된 세 개의 창. 왼쪽 창은 Neovim에서 열린 qmd 파일입니다. 오른쪽 위 창은 웹 브라우저로, qmd 문서가 Quarto에 의해 렌더링되어 표시됩니다. 세 번째 창은 qmd 파일의 코드 청크 실행 결과로 렌더링된 그래프입니다.

왼쪽의 .qmd 파일이 오른쪽의 HTML 문서로 렌더링됩니다. 이것이 Quarto 배포의 기본 모델입니다. 즉, 소스 문서를 가져와 HTML, PDF, MS Word 등 다양한 출력 형식으로 렌더링합니다.

이 튜토리얼에서는 matplotlib과 plotly 파이썬 패키지를 사용합니다. 설치 명령은 아래 표에 정리되어 있습니다.

Platform Commands
Mac/Linux 
Terminal
python3 -m pip install jupyter matplotlib plotly
Windows 
Terminal
py -m pip install jupyter matplotlib plotly
Note

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

렌더링 및 미리보기

간단한 예제(hello.qmd)를 몇 가지 형식으로 렌더링하는 것부터 시작하겠습니다. 자신의 환경에서 단계별로 따라 하려면 hello.qmd라는 새 파일을 만들고 다음 내용을 복사해 넣으세요.

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

렌더링과 미리보기를 위해 :를 눌러 명령 모드로 들어가 QuartoPreview 명령을 입력하세요(tab 키로 자동 완성을 사용할 수 있습니다). Kickstarter 구성에서는 space q(일반 모드에서 스페이스 바 뒤 q)로 시작하는 더 많은 단축키도 있습니다.

작동 원리

Quarto로 .qmd 파일을 렌더링하면, 실행 가능한 코드 블록이 Jupyter에서 처리되고 코드/마크다운/출력의 조합이 일반 마크다운으로 변환됩니다. 그다음 이 마크다운을 Pandoc이 처리하여 최종 형식을 생성합니다.

qmd 파일 -> Jupyter -> md -> pandoc -> PDF/MS Word/HTML로 이어지는 워크플로 다이어그램.

저작

간단한 변경을 해보고 다시 렌더링해 보겠습니다.

  1. theta를 정의하는 코드를 다음과 같이 변경하세요.

    theta = 4 * np.pi * r

  2. 일반 모드에서 :w 또는 ctrl-s로 파일을 저장하세요.2

문서가 렌더링되고 브라우저 미리보기가 업데이트됩니다. 이것이 Quarto 저작의 기본 워크플로입니다.

셀 실행

코드 셀을 반복 작업할 때 문서를 완전히 렌더링할 필요는 없습니다. 제공된 설정에서는 리더 키(<space>)를 누른 뒤 c(code)와 p(python) 또는 i(ipython)를 입력해 원하는 터미널을 열 수 있습니다.

키 입력 사이에 조금 기다리면 화면 아래쪽에 기존 키 바인딩을 알려주는 작은 창이 뜹니다.

ctrl과 Vim 방향키를 사용해 코드와 터미널 사이를 이동할 수 있고, 이 터미널 버퍼에서 삽입 모드로 들어가 Python REPL에 명령을 입력할 수 있습니다.

Quarto에서 Python REPL로 코드를 보내려면 코드 블록으로 이동한 다음 <space><cr>(스페이스 바 뒤 Enter)를 누릅니다. 여러 위치로 코드를 보내는 플러그인인 vim-slime이 어느 터미널로 보낼지 묻고, 가장 최근에 만든 터미널이 기본값으로 채워집니다.

RStudio처럼 ctrl+Enter로 코드를 보내고 싶다면, 터미널 에뮬레이터가 올바른 키 코드를 보내도록 설정해야 합니다. 예를 들어 kitty 터미널에서는 다음과 같이 설정합니다.

map ctrl+shift+enter no_op
map shift+enter send_text all \x1b[13;2u
map ctrl+enter send_text all \x1b[13;5u

이 설정은 kickstarter 구성에서 테스트된 값입니다.

hello.qmd에는 여러 유형의 콘텐츠가 있으니 각각을 조금씩 살펴보겠습니다.

YAML 옵션

파일 맨 위에는 문서 수준 옵션이 담긴 YAML 블록이 있습니다.

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

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

format: 
  html:
    code-fold: false

그런 다음 저장하여 문서를 다시 렌더링하세요. 이전에는 Code 버튼으로 숨겨져 있던 코드가 이제 플롯 위에 표시되는 것을 확인할 수 있습니다.

서술형 콘텐츠는 마크다운으로 작성합니다. 여기서는 제목과 아래 코드 셀에서 생성된 그림에 대한 상호 참조를 지정합니다.

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

여기 제시된 Matplotlib 코드는 익숙할 것입니다. 하지만 코드 셀 상단에 있는 label과 fig-cap 옵션은 생소할 수 있습니다. 셀 옵션은 특수 접두사가 붙은 주석(#|)으로 YAML 형식으로 작성합니다.

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

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

Note

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

다음 단계

다음 단계

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

  • 튜토리얼: 계산 — 실행 가능한 코드 블록의 동작과 출력을 원하는 방식으로 조정하는 방법을 배웁니다.

  • 튜토리얼: 작성 — 출력 형식과 인용, 상호 참조, 고급 레이아웃 같은 기술 문서 작성 기능을 더 알아봅니다.

Quarto에서 Neovim을 설치하고 사용하며 사용자화하는 방법을 더 알아보려면 Quarto에서 Neovim 사용하기 문서를 참고하세요.

Footnotes

  1. 이 비디오에서 소개됩니다.↩︎

  2. Kickstarter 구성을 사용하지 않는 경우 ctrl-s는 터미널을 대기 모드로 두며, ctrl+q를 눌러야 해제됩니다. 혼동될 수 있으니 유의하세요.↩︎