튜토리얼: 작성

도구 선택

개요

이 튜토리얼에서는 Jupyter Lab에서 Quarto 문서를 작성하는 방법을 보여줍니다. 특히 생성할 수 있는 다양한 문서 형식을 소개하고 목차, 수식, 인용, 상호 참조 등 구성 요소를 추가하는 방법을 설명합니다.

출력 형식

Quarto는 노트북을 수십 가지 출력 형식으로 렌더링할 수 있습니다. 기본값은 html 형식이지만, 문서 옵션에서 다른 형식(또는 여러 형식)을 지정할 수 있습니다.

형식 옵션

노트북을 만들고 여러 형식으로 렌더링되도록 정의한 뒤 각 형식에 옵션을 추가해 봅시다. 문서 옵션은 노트북 시작 부분의 “Raw” 셀에 있는 YAML에 지정된다는 점을 기억하세요. Raw 셀을 만들려면 노트북 상단에 셀을 추가하고 도구 모음에서 셀 유형을 Raw로 설정합니다.

Notebook formats.ipynb with a dropdown shown for a cell with three options: Code, Markdown, and Raw. Raw is highlighted.

이제 기본 문서 메타데이터와 기본 출력 형식을 추가해 봅시다.

---
title: "Quarto Document"
author: "Norah Jones"
format: pdf
jupyter: python3
---

기본 출력 형식으로 pdf를 지정했습니다(format 옵션을 제외하면 기본값은 html입니다).

이제 PDF 출력 제어를 위한 옵션을 추가합니다.

---
title: "Quarto Document"
author: "Norah Jones"
format: 
  pdf: 
    toc: true
    number-sections: true
jupyter: python3
---

여러 형식

작성하는 문서가 하나의 출력 형식만 갖는 경우도 있지만, 많은 경우 여러 형식을 지원하고 싶을 것입니다. 문서에 html과 docx 형식을 추가해 봅시다.

---
title: "Quarto Document"
author: "Norah Jones"
toc: true
number-sections: true
highlight-style: pygments
format: 
  html: 
    code-fold: true
    html-math-method: katex
  pdf: 
    geometry: 
      - top=30mm
      - left=20mm
  docx: default
jupyter: python3
---

여기에는 많은 내용이 있습니다. 조금 나누어 보겠습니다. 처음 두 줄은 출력 형식과 무관한 일반 문서 메타데이터입니다.

title: "Quarto Document"
author: "Norah Jones"

다음 세 줄은 모든 형식에 적용되는 문서 형식 옵션입니다. 그래서 루트 수준에 지정합니다.

toc: true
number-sections: true
highlight-style: pygments

그다음 format 옵션에 형식별 옵션을 지정합니다.

format:
  html: 
    code-fold: true
    html-math-method: katex
  pdf:
    geometry: 
      - top=30mm
      - left=30mm
  docx: default

html과 pdf 형식에는 각각 한두 개의 옵션이 지정되어 있습니다. 예를 들어 HTML 출력에서는 사용자가 코드 표시 여부를 제어할 수 있도록 code-fold: true를 지정하고, 수학 텍스트는 katex로 렌더링합니다. PDF는 여백을 정의합니다. docx 형식은 docx: default로 지정됩니다. 이는 해당 형식의 기본 옵션을 그대로 사용한다는 의미입니다.

렌더링

문서 옵션에 지정된 형식은 기본적으로 렌더링할 형식을 정의합니다. 위의 모든 옵션으로 노트북을 렌더링하려면 다음 명령을 실행합니다.

Terminal

quarto render notebook.ipynb

그러면 다음 파일이 생성됩니다.

notebook.html
notebook.pdf
notebook.docx

--to 옵션으로 하나 이상의 형식을 선택할 수 있습니다.

Terminal

quarto render notebook.ipynb --to docx
quarto render notebook.ipynb --to docx,pdf

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

문서 옵션에 지정하지 않은 형식도 필요하다면 렌더링할 수 있습니다.

Terminal

quarto render notebook.ipynb --to odt

odt 형식은 문서 옵션에 포함되어 있지 않으므로 해당 형식의 기본 옵션이 사용됩니다.

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

Terminal

quarto render notebook.ipynb --execute

섹션

목차와/또는 섹션 번호를 사용하면 독자가 문서를 더 쉽게 탐색할 수 있습니다. 문서 옵션에 toc 및/또는 number-sections를 추가하면 됩니다. 이 옵션들은 보통 모든 형식에 공통으로 적용되므로 루트 수준에 지정합니다.

---
title: Quarto Basics
author: Norah Jones
date: 'May 22, 2021'
toc: true
number-sections: true
jupyter: python3
---

## Colors

- Red
- Green 
- Blue

## Shapes

- Square
- Circle
- Triangle

## Textures

- Smooth
- Bumpy
- Fuzzy

이 문서를 HTML로 렌더링하면 다음과 같습니다.

Document with title Quarto Basics, author, and date. Table of contents is on the left-hand side with numbered items for each of the three sections: 1. Colors, 2. Shapes, 3. Textures. Each section is shown in the document with the list contents from the source ipynb.

목차와 섹션 번호의 동작을 제어하는 다양한 옵션이 있습니다. 자세한 내용은 출력 형식 문서(예: HTML, PDF, MS Word)를 참고하세요.

수식

Jupyter Lab의 마크다운 셀에 LaTeX 수식을 추가할 수 있습니다.

Einstein's theory of special relatively that expresses the equivalence of mass and energy:

$E = mc^{2}$

$E = mc^{2}$

수식은 셀을 실행할 때 렌더링됩니다.

Rendered notebook with LaTeX equation shown for E equals mc squared.

인라인 수식은 $…$ 로 감싸며, 새 줄(display) 수식을 만들려면 $$…$$를 사용합니다. 자세한 내용은 마크다운 수식 문서를 참고하세요.

인용

Quarto 문서에서 다른 작업을 인용하려면 먼저 지원 형식(BibTeX 또는 CSL)의 참고문헌 파일을 만듭니다. 그런 다음 bibliography YAML 메타데이터 옵션으로 참고문헌을 연결합니다.

다음은 참고문헌과 단일 인용을 포함한 노트북입니다. 마크다운 셀은 실행되지 않으므로 문법을 그대로 볼 수 있습니다.

---
title: Quarto Basics
format: html
bibliography: references.bib
jupyter: python3
---

## Overview

Knuth says always be literate [@knuth1984].

```{python}
1 + 1
```

## References

참고문헌 항목은 @citeid 문법으로 인용합니다.

 Knuth says always be literate [@knuth1984].

참고문헌은 문서 끝에 포함되므로 노트북 하단에 ## References 제목을 추가합니다.

렌더링 결과는 다음과 같습니다.

Rendered notebook with references section at the bottom the content of which reads 'Knuth, Donald E. 1984. Literate Programming. The Computer Journal 27 (2): 97-111.'

@ 인용 문법은 접두사, 접미사, 위치 지정자, 본문 내 인용을 포함해 매우 유연합니다. 자세한 내용은 인용 문서를 참고하세요.

상호 참조

상호 참조는 그림, 표, 수식, 섹션에 번호와 하이퍼링크를 제공해 문서 탐색을 쉽게 합니다. 상호 참조 가능한 항목에는 일반적으로 레이블(고유 식별자)과 캡션이 필요합니다.

아래 노트북은 다양한 항목을 상호 참조하는 방법을 보여줍니다. 이번에도 문법을 보이기 위해 마크다운 셀은 실행되지 않은 상태입니다.

---
title: Quarto Crossrefs
format: html
jupyter: python3
---

## Overview

See @fig-simple in @sec-plot for a demonstration of a simple plot. 

See @eq-stddev to better understand standard deviation.

## Plot {#sec-plot}

```{python}
#| label: fig-simple
#| fig-cap: "Simple Plot"
import matplotlib.pyplot as plt
plt.plot([1,23,2,4])
plt.show()
```

## Equation {#sec-equation}

$$
s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}
$$ {#eq-stddev}

\[ x + 1 \]

이 예제는 섹션, 그림, 수식을 상호 참조합니다. 아래 표는 각 항목을 어떻게 표현하는지 보여줍니다.

Entity	Reference	Label / Caption
Section	`@sec-plot`	ID added to heading: `# Plot {#sec-plot}`
Figure	`@fig-simple`	YAML options in code cell: `#\| label: fig-simple #\| fig-cap: "Simple Plot"`
Equation	`@eq-stddev`	At end of display equation: `$$ {#eq-stddev}`

그리고 마지막으로 이 노트북을 렌더링한 결과는 다음과 같습니다.

Rendered page with linked cross references to figures and equations.

자세한 내용은 상호 참조 문서를 참고하세요. 캡션과 참조 텍스트(예: “Figure” 대신 “Fig.” 사용)를 커스터마이즈하는 방법도 포함되어 있습니다.

Callout

Callout은 특정 개념에 추가 주의를 끌거나, 특정 콘텐츠가 보조 정보이거나 일부 시나리오에만 적용됨을 더 명확하게 나타내는 데 유용합니다.

Callout은 특수 callout 속성을 가진 마크다운 div입니다. 다음은 마크다운 셀에서 callout을 만드는 예시입니다.

::: {.callout-note}
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Quarto로 문서를 렌더링하면 callout이 의도한 대로 표시됩니다.

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Callout 유형과 모양 옵션에 대한 자세한 내용은 Callouts 문서를 참고하세요.

아티클 레이아웃

Quarto 아티클 본문은 기본적으로 약 700픽셀의 너비를 갖습니다. 이 너비는 가독성 최적화를 위해 선택됩니다. 이 경우 문서 여백에 사용 가능한 공간이 생기며, 이를 활용하는 방법이 몇 가지 있습니다.

이 노트북에서는 reference-location 옵션으로 각주를 오른쪽 여백에 배치하도록 지정합니다.

또한 column: screen-inset 셀 옵션으로 그림이 화면 전체 폭을 차지하되, 약간의 인셋을 두도록 지정합니다.

---
title: Quarto Layout
format: html
reference-location: margin
jupyter: python3
---

## Placing Colorbars

Colorbars indicate the quantitative extent of image data.
Placing in a figure is non-trivial because room needs to
be made for them. The simplest case is just attaching a 
colorbar to each axes:^[See the [Matplotlib Gallery](https://matplotlib.org/stable/gallery/subplots_axes_and_figures/colorbar_placement.html) to explore colorbars further].

```{python}
#| code-fold: true
#| column: screen-inset
import matplotlib.pyplot as plt
import numpy as np

fig, axs = plt.subplots(2, 2)
fig.set_size_inches(20, 8)
cmaps = ['RdBu_r', 'viridis']
for col in range(2):
    for row in range(2):
        ax = axs[row, col]
        pcm = ax.pcolormesh(
          np.random.random((20, 20)) * (col + 1),
          cmap=cmaps[col]
        )
        fig.colorbar(pcm, ax=ax)
plt.show()
```

렌더링 결과는 다음과 같습니다.

Document with Quarto Layout title at the top followed by Placing Colorbars header with text below it. Next to the text is a footnote in the page margin. Below the text is a toggleable code widget to hide/reveal the code followed by four plots displayed in two rows and two columns.

여백에는 인용, 각주, aside를 배치할 수 있습니다. 또한 그림, 표 또는 다른 콘텐츠에 대한 사용자 정의 열 폭을 지정할 수도 있습니다. 자세한 내용은 아티클 레이아웃 문서를 참고하세요.

더 알아보기

이제 Quarto 사용의 기본을 익혔습니다! 문서를 만들고 커스터마이즈하는 데 익숙해졌다면 다음 주제를 더 탐색해 보세요.

프레젠테이션 — 문서를 만들 때 배운 동일한 문법으로 PowerPoint, Beamer, Revealjs 프레젠테이션을 작성할 수 있습니다.
웹사이트 — 문서 모음을 웹사이트로 배포하세요. 웹사이트는 다양한 탐색 방식과 전체 텍스트 검색을 지원합니다.
블로그 — 소개 페이지, 유연한 글 목록, 카테고리, RSS 피드, 20개 이상의 테마를 갖춘 블로그를 만들 수 있습니다.
책 — 인쇄(PDF, MS Word)와 온라인(HTML, ePub) 형식으로 책과 원고를 만들 수 있습니다.
상호작용 — 독자가 개념과 데이터를 더 깊이 탐색할 수 있도록 대화형 구성 요소를 포함할 수 있습니다.