Quarto для соавтора курса: как написать лекцию

Лекция курса состоит из слайдов, главы книги, задач и ноутбука. Все они пишутся в Quarto — это Markdown с формулами LaTeX и ячейками кода Python, которые выполняются при сборке. Образец — лекция 1 «Python, NumPy и Numba»: открывайте её файлы рядом с этой инструкцией. Как сохранять работу в Git, описано в git-guide.md; требования к содержанию лекций — в authoring-guide.md.

Один раз: установка

  1. Quarto: https://quarto.org/docs/get-started/ (проверка: quarto --version).

  2. Python 3.11 или новее и пакеты курса (из папки репозитория):

    python -m pip install -r requirements.txt

    Удобно держать отдельное окружение (python -m venv ~/venvs/numerical, затем source ~/venvs/numerical/bin/activate); папку окружения не кладите внутрь репозитория.

  3. Редактор: VS Code с расширением Quarto (подсветка, предпросмотр по кнопке) или любой текстовый редактор.

  4. LaTeX на своём компьютере не нужен: слайды и ноутбуки собираются без него, а книга на сайте не публикуется.

Файлы лекции

Пока лекция не опубликована, у неё нет номера, и все её файлы лежат в planned/ под именем slug (например, heat_equation):

Что Неопубликованная лекция Опубликованная (образец — лекция 1)
слайды ru/slides/planned/<slug>.qmd ru/slides/01_python_numpy_numba.qmd
ноутбук ru/slides/planned/notebooks/<slug>.qmd ru/slides/notebooks/01_python_numpy_numba.qmd
глава книги ru/book/planned/<slug>.qmd ru/book/chapters/01_python_numpy_numba.qmd
задачи _includes/exercises/planned/<slug>-ru.qmd _includes/exercises/01_python_numpy_numba-ru.qmd
рисунки shared/figures/<slug>/

Заготовки слайдов, главы и задач уже есть для всех лекций из программы; ноутбук создаётся по образцу. Публикацию — номер в имени файла, перенос из planned/, списки в _quarto.yml, ссылки на страницах курса — делает Д. В. Наумов. Английские версии (en/) пишутся позже.

Ноутбук — источник кода

Весь код лекции живёт в ноутбуке; слайды показывают его ячейки, а не копируют их. Ноутбук пишется как .qmd: текст Markdown и ячейки

```{python}
#| label: walk-simulate
rng = np.random.default_rng(seed=1)
steps = rng.choice([-1, 1], size=(2000, 1000))
```
  • #| label: — имя ячейки, по нему ячейка попадает на слайд. Только латиница, цифры и дефис, без повторов.
  • Ячейка с рисунком: метка начинается с fig- и есть подпись, #| label: fig-walk-msd и #| fig-cap: "...". С меткой без fig- рисунок при встраивании на слайд пропадает.
  • Шапку (YAML) ноутбука скопируйте из образца и поменяйте только title: в ней настроены оглавление, раскладка страницы и разрешение рисунков.
  • В начале ноутбука — импорт и печать версий пакетов (см. образец).
  • Случайные числа — только из генератора с явным seed.
  • Время выполнения печатается, а не вписывается в текст числом: на другой машине оно будет другим.

При сборке Quarto выполняет ноутбук, делает из него страницу сайта и скачиваемый файл .ipynb без результатов (скрипт scripts/export_notebooks.py). Студент скачивает .ipynb и запускает его в Jupyter или в Google Colab. Сами .ipynb в репозиторий не коммитятся.

Слайды

Шапка файла:

---
title: "Теплопроводность и диффузия"
subtitle: "Численные методы для физиков"
author: "..."
format: revealjs
---

Основные приёмы (все есть в образце):

Что Как
раздел лекции (тёмный титульный слайд) # Численный метод
слайд ## Идея метода
список - пункт
формула в строке / выключная $\sigma\propto1/\sqrt n$ / $$ ... $$
выделенный вывод ::: {.takeaway} … :::
ячейка ноутбука с кодом и результатом {{< embed notebooks/<slug>.qmd#label echo=true >}}
только результат (рисунок) {{< embed notebooks/<slug>.qmd#fig-label >}}
рисунок из файла ![](shared/figures/<slug>/name.png){width=70%}
две колонки :::: {.columns} ::: {.column width="50%"} … ::: ::::
пошаговый показ строка . . . между частями слайда

Слайд 1600×900: на нём помещаются 12–15 строк кода или один рисунок с подписью. Длинный код остаётся в ноутбуке, на слайд идут ключевые ячейки. Порядок разделов задаёт заготовка: задача → аналитический эталон → метод → код и эксперименты → ловушки → итоги и задачи.

Глава книги

Глава — развёрнутый текст лекции для самостоятельного чтения. Шапка: title и description (аннотация), затем блок ::: {.chapter-opening}. Код в главе выполняется при сборке, как в ноутбуке, но ячейки ноутбука сюда не встраиваются: книга — отдельный проект Quarto. Поэтому в главе короткие ячейки с самым важным и ссылка на ноутбук.

  • Рисунок: ячейка с #| label: fig-имя и #| fig-cap: "..."; ссылка в тексте — @fig-имя.
  • Формула с номером: $$ ... $$ {#eq-имя}, ссылка — @eq-имя.
  • Задачи подключаются в конце главы строкой {{< include ... >}} (см. образец).
  • Книга собирается и в PDF, поэтому в тексте нет HTML и интерактивных элементов.

Задачи

Файл задач подключается и в страницу задач у слайдов, и в главу книги. Три задачи: аналитический эталон, численный эксперимент, исследовательская. Заголовки строго в форме ## Задача 1. Название: по ним книга оформляет блок задач.

Посмотреть результат

Из папки репозитория:

quarto preview ru/slides/planned/heat_equation.qmd

Откроется браузер; при каждом сохранении файла страница обновится. Так же смотрятся ноутбук (quarto preview ru/slides/planned/notebooks/heat_equation.qmd) и глава (quarto preview ru/book/planned/heat_equation.qmd). Остановить — Ctrl+C в терминале. Файлы .html и папки *_files, которые появятся рядом, в Git не попадают.

Для опубликованных лекций собирается весь проект: make help показывает цели (make ru-slides, make ru-html).

Перед pull request

  • Ноутбук выполняется сверху вниз без ошибок (quarto preview или «Restart & Run All» в Jupyter).
  • Слайды и глава собираются без ошибок; формулы и рисунки на месте.
  • Каждый численный результат проверен по эталону; в ноутбуке напечатаны версии пакетов, у генератора случайных чисел есть seed.
  • В Git добавлены только файлы своей лекции (git status).

Частые ошибки

  • YAML-шапка: отступы — пробелы, не табуляция; строки с двоеточием — в кавычках.
  • Ошибка в ячейке кода останавливает сборку. Сообщение Quarto называет ячейку: исправьте её в ноутбуке и проверьте ноутбук отдельно.
  • $ в тексте начинает формулу; денежный знак пишется как \$.
  • Формулы в заголовках разделов книги ломают сборку PDF: заголовок пишется словами, формула — в тексте под ним.
  • Embed не находит ячейку: проверьте #| label: и путь к ноутбуку; ноутбук должен лежать в папке notebooks/ рядом со слайдами.
  • Кириллица в именах файлов и метках не допускается: только латиница, цифры, _ и -.