Quarto でレポート執筆（M1 Mac + VSCode）

こんにちは．さんげん（[@Sangen_u](https://twitter.com/Sangen_u)）です．今回は Quarto を導入し，これを使ってレポートを書く方法を解説していきます．

# はじめに-なぜ Quarto を使うのか
## Quarto とは何か

https://quarto.org

[公式サイト](https://quarto.org)には
>Quarto® is an open-source scientific and technical publishing system built on Pandoc


とあります．Rmarkdown を使ったことがある人は Rmarkdown を Python，Julia，R で使えるように拡張したものであると理解すればわかりやすいでしょう（Quarto とは何か，ということについての説明は[参考文献1](https://qiita.com/Nobukuni-Hyakutake/items/112a7bd5b34abd446395)も参考になります．今回は環境構築および設定の説明が長くなりそうなのでこの辺の説明は簡潔にしておきます）．

## Quarto を使うモチベーション
さて，今回私が Quarto を導入するきっかけになったのは，大学の講義で Python を用いて作成した図を使ってレポートを書く機会があったことです．レポートは pdf で提出することになっているので，作成方法として
1. Python スクリプトを書いて出力した図を LaTeX に取り込む
2. Jupyter Notebook + Pandoc で PDF 出力する

などが考えられますが，前者は図を修正する必要が出たときに Python スクリプトに戻って修正→図を出力し直して保存というステップを踏むのが面倒ですし，後者は図の修正は容易ですがレポートの体裁がなかなか整わない（これは VSCode で Jupyter Notebook のメタデータを編集するのが面倒であったり，作成した図にキャプションをつけるのが難しいことによるものです）という悩みがありました．
そこで，Quarto を導入したところこれらの悩みが一挙に解消したというわけです．

# この記事でやること
1. Quarto を導入する．
2. VSCode の Quarto 用プラグインを導入する．
3. Quarto を VSCode で編集し，**日本語の** PDF を出力する．

以下のセクションで実際に M1 Mac と VSCode を使った Quarto の導入手順を解説していきます．

# Quarto の環境構築
基本的に[公式ドキュメント](https://quarto.org/docs/get-started/)に丁寧に書かれていますが，ここでは私が実際に行った導入手順を紹介します．また，[参考文献1](https://qiita.com/Nobukuni-Hyakutake/items/112a7bd5b34abd446395)も参考になります．

## PC の環境
- OS : Mac OS Ventura バージョン13.0
- CPU : Apple M1 Pro

## 前提
本記事では，
- Homebrew
- VSCode
- Jupyterlab (あるいはJupyter Notebook)
- LaTeX

が既に導入されていることを前提としています．これらをまだ導入していない方は，VSCode と Jupyterlab に関しては[参考文献1](https://qiita.com/Nobukuni-Hyakutake/items/112a7bd5b34abd446395)を，Homebrewについては[参考文献2](https://qiita.com/Takayoshi_Makabe/items/742ab1da1556cd54a78f)を，LaTeX に関しては[参考文献3](https://zenn.dev/thor/articles/732c3e007f77ee)を参考に導入をしてください．

## Quarto の導入
https://formulae.brew.sh/cask/quarto

上記のサイトにあるインストールコマンドをターミナルに打ち込んで homebrew 経由で導入しました．Rosseta をインストールするよう警告が出たので，ターミナルに出てきたメッセージに従って Rosseta をインストールしたのち，再度インストールコマンドをターミナルに打ち込んでインストールに成功．これで Quarto の導入は終わりです．

## VSCode の Quarto 用プラグインの導入
Visual studio codeを開き、左側の拡張機能アイコンをクリック．"Marketplace で拡張機能を検索する"のボックスに "Quarto" と入力し検索すると，拡張機能 Quarto が表示されるのでインストールしました．
これにて Quarto の環境構築は終了です．

## VSCode の Python 用プラグインの導入
ここからは Python を用いることを想定して Visual studio code の設定を進めていきます．以下では Quarto が参照する Python 環境を指定する設定を行います．
先ほどと同様に"Marketplace で拡張機能を検索する"のボックスに "Python" と入力し表示される拡張機能 Python をインストールします．
次に Python 拡張機能の設定を開き，"Python : Default Interpriter Path" と書かれた欄に使う Python 環境の PATH を入力します（ターミナルで "which python" とコマンド入力すると Python 環境の PATH が表示されるので，それをコピペすればよいです）． Quarto はこの欄で示された Python 環境を用います．
以上で Quarto を使う準備が整いました．


# Quarto での日本語 PDF 出力
Quarto の環境構築が終わったので，いよいよ**日本語の** PDF を出力していきたいと思います．以下がサンプルコードです．拡張子は `.qmd` で指定してください．

~~~ md:sample.qmd
---
title: "ほげほげ"
author: "さんげん"
date: "2022-10-27"
execute:
  echo: false
format: 
  pdf:
    include-in-header:
      - text: 
          \usepackage{physics}
jupyter: python3
pdf-engine: lualatex
documentclass: ltjsarticle
classoption: lualatex,ja=standard
editor: visual
---

# 日本語で書けます

なんかぐるぐるしたやつが @fig-polar として出ます．

```{python}
#| label: fig-polar
#| fig-cap: "日本語のキャプションも大丈夫"

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

数式も書けます．
$$ \int f(x)\dd{x} $$
$\int f(x)\dd{x}$
~~~




まず最初に一番上の `---` で囲まれた部分ですが，これが YAML ヘッダというもので，出力の際のメタデータを記述できます．
今回のポイントは
- `execute:
  echo: false` の2行でコード部分を隠す
- `format: 
  pdf:
    include-in-header:
      - text: 
          \usepackage{physics}` の5行で LaTeX 出力する際に physics パッケージを使えるようにしている
- `pdf-engine: lualatex` で lualatex でコンパイルするようにしている

ことです．lualatex でコンパイルしているのは日本語を出力するためで，ここは xelatex を選んでも良いです．しかし，Quarto は Pandoc ベースであるため (u)platex は使うことができません．日本語を出力する際の latex エンジン周りの設定については[参考文献4](https://qiita.com/kojix2/items/2aae818cfa9bbb68087f)も参照してください．

ヘッダより後のテキスト部分に関しては基本的に Markdown 記法で書けます．サンプルに書いた書き方で出力した図のキャプションやラベルが設定できるのも便利ですね．日本語対応の LaTeX エンジンを使っていればキャプションには日本語も設定できます．

`.qmd` ファイルが完成したら，VSCode のコマンドパレットから `Quarto: Render PDF` を実行すれば PDF が出力されます．サンプルコードを出力したものがこちら．![スクリーンショット 2022-10-29 4.51.28.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2766222/9f878260-284e-6dd4-3530-2a04baf0da74.png)

`.qmd` ファイルの中身の書き方は公式サイトに詳しく載っているので英語でよければそちらを参照すると良いかもしれません．私も便利だと思った機能があればまた別の記事にまとめるなどして紹介することを考えています．

https://quarto.org/docs/guide/

# おわりに
今回は Quarto の環境構築手順および日本語 PDF の出力方法について記事を書きました．かなり手順を省略していますが，Quarto 自体まだ誕生から日が浅く，まとまった日本語の情報が少ないように感じたので，導入から出力まで一通りの情報をまとめておこうと思い本記事の執筆を思い立ちました．足りないところやわかりにくいところも多々あると思うので，これからも暇を見つけて改訂していく予定です．
また，今回は Python を例にして説明しましたが，Julia や R でも同様に出力することができます．
この記事によって Quarto を使う人の数が少しでも増えることを期待しています．

### 参考文献
1. https://qiita.com/Nobukuni-Hyakutake/items/112a7bd5b34abd446395
2. https://qiita.com/Takayoshi_Makabe/items/742ab1da1556cd54a78f
3. https://zenn.dev/thor/articles/732c3e007f77ee
4. https://qiita.com/kojix2/items/2aae818cfa9bbb68087f