2  Установка и начало работы с Quarto

2.1 Установка Quarto

Для установки Quarto, необходимо зайти на начальную страницу проекта https://quarto.org/ и нажать на кнопку Get Started.

Рисунок 2.1: Начальная страница Quarto

Установка происходит в два этапа.

  • Шаг 1. Установка интерфейса командной строки (CLI) для актуальной операционной системы (Windows, Linux или macOS). Рекомендуется устанавливать стабильную версию Current Release со страницы загрузки, а не Pre-release-версии.
Рисунок 2.2: Установка Quarto в macOS
  • Шаг 2. Установка плагина для интегрированной среды разработки (IDE). Выберите подходящий плагин для вашей среды разработки, будь то Visual Studio Code, RStudio, Positron, Jupyter или иной текстовый редактор. Помимо этого, существует возможность установить Quarto-плагин, например, для Sublime Text или Emacs.

2.2 IDE-инструменты

2.2.1 RStudio

Если Quarto CLI уже установлен, то RStudio обнаружит это и автоматически включит функции Quarto. В качестве альтернативы существует версия Quarto уже встроенная в RStudio.

Создание нового Quarto-документа в RStudio с расширением *.qmd происходит как File : New File : Quarto document…, что открывает новый документ на основе шаблона.

Рисунок 2.3: Окно создания документа Quarto в RStudio

В открывшемся окне можно выбрать вид документа (статичный, презентация или интерактивный), указать заголовок документа, автора, выбрать каким образом будет рендериться документ, будет ли использован визуальный редактор.

Кроме того, можно создать Quarto-документ как проект, следуя командам File : New Project… : Create Project : Project Type.

Рисунок 2.4: Окно создания Quarto-документа в RStudio как проекта

Редактирование документа возможно в двух режимах: Source (текст + код) и Visual (визуальный). Переключение кнопок с Source на Visual позволяет перейти в режим визуального редактирования, который близок к WYSIWYG-редактору и может быть особенно полезен, например, для создания таблиц в документах.

Рисунок 2.5: Вид визуального редактора Quarto в RStudio

Если в визуальном режиме нажать на /, то в появившемся меню можно выбрать элемент для вставки: блок для кода, список и т.д. Более подробно о работе в визуальном режиме можно посмотреть на странице документации.

Рисунок 2.6: Вставка элементов Quarto в визуальном режиме в RStudio

Для того чтобы запустить рендер проекта в RStudio, который преобразует Quarto-документ в выходной формат, достаточно нажать на кнопку Render, которая находится вверху панель инструментов, либо использовать клавиатурное сочетание Shift+Control+K или Shift+Command+K в зависимости от установленной операционной системы. Для остановки фонового задания (рабочего процесса) необходимо перейти на панель Background Jobs, находящейся рядом с консолью, и нажать значок Stop background job.

Рисунок 2.7: Кнопка рендеринга для документа Quarto в RStudio

Еще одна возможность сделать рендер Quarto-документа в RStudio — это использование Quarto как R-библиотеки, например:

R
quarto_render("document.qmd", output_format = "pdf")

Подробно о работе в RStudio можно посмотреть на соотетствующей странице документации.

2.2.2 Visual Studio Code (Positron)

Альтернативно, Visual Studio Code (или VS Code) позволяет редактировать как документы с расширением *.qmd, так и с *.ipynb-ноутбуками. Помимо предварительного просмотра документов, доступна подсветка синтаксиса для встроенных языков, автоматические подсказки, автозавершение для языков программирования, клавиатурные сочетания, предварительный просмотр в режиме реального времени для LaTeX, а также диаграмм Mermaid и Graphviz.

Рисунок 2.8: Вид редактора в IDE VS Code

Также большим преимуществом VS Code является большое количество полезных плагинов, например, для автоматической проверки орфографии, работы с Git, работы с проектами и многое другое.

Рисунок 2.9: Создание Quarto-файла в IDE VS Code

Такой функционал VS Code как удобный проводник, мини-карта, встроенная проверка для опций YAML и обилие расширений делает IDE отличным инструментом для создания больших Quarto-проектов, например книг. Работа VS Code в Quarto описана на странице документации.

Рисунок 2.10: Команды Quarto-файла в IDE VS Code в Палитре команд

В 2024 году в Posit PBC представили новый IDE, направленный на анализ данных, который называется Positron и во многом основан на VS Code. Помимо привычных настроек VS Code, Positron предоставляет дополнительные возможности для создания документов Quarto, например, встроенные шаблоны.

Рисунок 2.11: Открытие Quarto-проекта в IDE Positron

2.2.3 Jupyter

Для тех, кто программирует на Julia или Python, более привычным инструментом является система Jupyter-ноутбуков. Убедитесь в том, что у вас установлен язык программирования (например, Python 3), создано и активировано окружение и установлен Jupyter. Кратко напомним основные шаги для дальнейшей работы. Здесь мы будем использовать менеджер пакетов в Python uv, который, несмотря на новизну, успел себя зарекомендовать, однако можно использовать pip или conda, аналогичная инструкция приведена на сайте Quarto.

Шаг 1. Установите uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Terminal
pip install uv

Шаг 2. Создайте при необходимости окружение:

Terminal
uv venv my-env

Если необходимо выбрать версию Python, то это нужно добавить в команду:

Terminal
uv venv  --python 3.13 my-env

Активируйте окружение:

Terminal
source my-env/bin/activate
Terminal
.\myenv\Scripts\activate

Шаг 3. Установите Jupyter:

Terminal
uv pip install jupyter

Проверьте корректность установки Jupyter:

Terminal
quarto check jupyter
Рисунок 2.12: Результат проверки корректности установки Jupyter

Запустите Jupyter Notebook:

Terminal
jupyter notebook

Аналогично можно запустить JupyterLab:

Terminal
uvx jupyter lab

Приведем пример Jupyter-ноутбука в Quarto.

Рисунок 2.13: Пример Jupyter-ноутбука в Quarto на языке Python

Для того, чтобы создать Quarto-пример в Jupyter, необходимо в преамбулу *.qmd-документа добавить YAML-вставку и затем отрендерить *.ipynb-ноутбук, перейдя в терминале в корневой каталог проекта и набрав команду подобно тому, как написано ниже.

Terminal
quarto render hello_Python.ipynb --to html
Рисунок 2.14: Пример результата рендеринга ноутбука
УведомлениеЗамечание

Если вместо Python используется Julia, то в преамбуле необходимо в качестве ядра указать актуальную версию, например, jupyter: julia-1.12.

2.3 Работа с проектами

2.3.1 Создание нового проекта с помощью интерфейса командной строки

Проект Quarto включает несколько файлов, расположенных в одной папке. В частности, в папке проекта обязательно присутствует файл _quarto.yml, который устанавливает общие параметры для всех документов проекта.

Существует несколько вариантов для создания Quarto-проекта: в IDE, например, в RStudio, VS Code и Positron, а также с помощью команд в терминале используя интерфейс командной строки (то есть CLI).

Рисунок 2.15: Получить помощь по командам Quarto CLI можно с помощью команды quarto --help в терминале

Если необходимо создать проект в текущей директории, то это можно сделать, указав в командной строке тип проекта <project_type> (например, website, website:blog, book, manuscript).

Terminal
quarto create-project --type <project_type>
Рисунок 2.16: Пример создания проекта веб-сайта из командной строки в текущей директории

Quarto-проекты в новой директории можно создавать через командную строку, при этом Quarto выдаст интерактивную подсказку с запросом типа проекта, имени каталога и названия проекта.

Terminal
quarto create project <project_type> my_project_folder
Рисунок 2.17: Пример создания проекта веб-сайта в новой директории

Пример структуры созданного проекта веб-сайта в новой директории:

quarto-example/my_website
├── _quarto.yml
├── about.qmd
├── index.qmd
└── styles.css

После создания проекта для того, чтобы отрендерить проект и открыть его для предварительного просмотра, можно воспользоваться командой quarto preview:

Terminal
quarto preview project_name
Рисунок 2.18: Пример предварительного просмотра проекта

Предварительный просмотр веб-сайта откроется в новом веб-браузере. При редактировании и сохранении index.qmd (или других файлов, таких как about.qmd) предварительный просмотр автоматически будет обновляться.

2.3.2 Рендеринг документов Quarto

Кратко опишем идею того, как происходит рендеринг проектов Quarto. Сначала Knitr (в R) или Jupyter (в Pyhton или Julia) выполняет все фрагменты кода *.qmd-файла и создает новый Markdown-документ с расширением *.md, который включает в себя код и его выходные данные. Отметим, что один и тот же *.qmd-документ может служить источником для различных выходных форматов. Ниже показаны примеры команд.

Terminal
quarto render hello.qmd --to html
quarto render hello.qmd --to docx
quarto render hello.qmd --to pdf
quarto render hello.qmd --to epub
quarto render hello.qmd --to pptx
quarto render hello.qmd --to revealjs
Рисунок 2.19: Организация рендеринга документов в Quarto (источник)

Созданный Markdown-файл затем обрабатывается Pandoc для преобразования в различные форматы файлов, включая HTML, PDF, MS Word и другие поддерживаемые форматы.

УведомлениеЗамечание

Перед публикацией проекта в сети Интернет обязательно нужно предварительно сделать полный рендер проекта с помощью команды quarto render.

При рендеринге не будут обрабатываться файлы вида: _file_name.*, .file_name.*, а также файлы, соответствующие .*md.

При работе с проектом мы периодически обращаемся к его предварительному просмотру используя команду ниже с различными параметрами.

Terminal
quarto preview hello.qmd

Отличие команд preview и render в том, что для preview Quarto отрендерит ровно столько элементов проекта, сколько нужно для отображения запрошенного документа и открытия предварительного просмотра. Когда происходит взаимодействие с предварительным просмотром, например, переход по ссылке в одном документе с одной страницы на другую, Quarto отрендерит и отобразит все дополнительные файлы по мере необходимости.

В Quarto также возможно осуществлять рендеринг файлов, содержащих скриптов (*.r, *.py или *.jl), которые форматируются как ноутбуки.

Terminal
quarto render script.r
quarto render script.py
quarto render script.jl

Синтаксис ноутбуков зависит от того, используете ли вы движок Jupyter (для скриптов R, Python и Julia) или Knitr (для R). В любом случае скрипт должен начинаться с ячейки разметки, которая включает блок заголовка YAML.

Например, для Jupyter ячейки Markdown разделяются символами # %% [markdown] и могут включать содержимое в виде однострочных комментариев (#) или многострочных строк ("""). Иными словами, синтаксис очень схож с тем, что используется в Jupytext.

script.py
# %% [markdown]
# ---
# title: Привет, пингвины
# author: А.А. Автор
# date: today
# ---

# %%
#| echo: false
import polars as pls
df = pls.read_csv("palmer-penguins.csv")

# %% [markdown]
"""
## Исследование данных

См. рисунок @fig-bill-sizes для определения параметров.
"""

# %% 
#| label: fig-bill-sizes
#| fig-cap: Параметры пингвинов
                                          
import matplotlib.pyplot as plt           
import seaborn as sns

g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5)
g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend()

Удобство подобного подхода заключается в том, что мы можем вместо Jupyter *.ipynb использовать скрипт как выше, что позволяет обращаться к ноутбуку как текстовым файлу, это дает возможность работать с ноутбуками в Git.

Аналогичным способом определяется R-скрипт следуя статье по преобразованию R-скрипта в отчет. Скрипты, визуализируемые с помощью Quarto, должны начинаться с заголовка YAML с использованием #'-комментариев. Код R является основным содержимым скрипта R и включен без каких-либо ограничений. Параметры ячеек кода указываются с #|-комментариями и применяются к коду под ними. Содержимое Markdown включается в строки, начинающиеся со специального #|-комментария.

script.r
#' ---
#' title: Привет, пингвины
#' author: А.А. Автор
#' date: today
#' format: html
#' ---

library(tidyverse)
library(palmerpenguins)

#' ## Пример графика
#' См. @fig-bill-sizes для точных данных.

#| label: fig-bill-sizes
#| fig-cap: Пример графика
#| warning: false
penguins |> 
  na.omit() |> 
  ggplot(aes(x = bill_length_mm,
             y = bill_depth_mm,
             fill = species,
             size = body_mass_g)) + 
  geom_point(pch = 21,
             color = "white", 
             alpha = 0.7) +
  scale_x_continuous(name = "Длина клюва",
                     labels = function(x) str_c(x, " мм")) +
  scale_y_continuous(name = "Высота клюва",
                     labels = function(x) str_c(x, " мм"))

Более подробно по рендерингу скриптов можно прочитать на странице документации.

Заключение

Здесь мы рассмотрели самые различные вопросы, начиная от установки Quarto, выбора IDE-инструментов, до создания собственных проектов и возможностей рендеринга.