howto.md

Преподавателям и разработчикам

Для создания онлайн-книги используется Jupyter Book (не Notebook). Jupyter Book представляет собой генератор статических сайтов (static site generator). Генератор создаёт из исходных файлов (MyST Markdown) веб-страницы (HTML), и связывает их ссылками.

Внешний вид онлайн-материалов в Jupyter Book и набор встроенных инструментов оптимизирован под книгу естественно-научного содержания:

• Книга разбивается на секции, главы и разделы. Содержание формируется автоматически.
• Можно публиковать уравнения (LaTeX) и код (исполняемый и неисполняемый). Исполняемый код возвращает значение, которое преобразуется в материалы, подобно ноутбукам Jupyter. Например, можно программно создавать графики (Plots.jl) или таблицы (PrettyTables.jl).
• Есть перекрёстные ссылки на разделы книги, уравнения, блоки кода, рисунки.
• Есть ссылки на литературу, необходимая литература помещается в BibLaTeX файл, а список использованной литературы формируется автоматически.

Содержание

• Установка необходимого
• Изменение материалов книги и создание новых
• Публикация книги и изменений
• Обзор make команд
• Вопрос-ответ

Используемые технологии

• Docker
• Python 3 и Julia
• Jupyter Book
• MyST Markdown
• make

Полезные ссылки

• Документация Jupyter Book, https://jupyterbook.org/.
• Синтаксис MyST Markdown, https://myst-parser.readthedocs.io/en/latest/index.html.

Установка необходимого

Чтобы создать книгу, понадобится Docker. Docker позволяет поместить необходимые для создания книги инструменты в контейнер, минимизируя влияние внешнего окружения.

Скачивание Docker и исходных файлов книги

1. Установите Docker с официального сайта https://www.docker.com/.
2. Запустите Docker Desktop для проверки работоспособности.
3. Склонируйте git-репозиторий книги с исходными файлами git clone ....

Далее создаётся Docker образ (image) для работы с книгой. Образ включает в себя ubuntu, python3, julia и необходимые библиотеки. Полное описание вы найдёте в файле Dockerfile. Создание образа занимает около 10 минут и требует примерно 2 ГиБ памяти.

Перейдите в корневую директорию репозитория книги (туда, где Makefile). Затем выполните команду.

make docker-image

В результате создаётся образ с названием compthermobook-image (см. Makefile). Вы также его увидите в Docker Desktop во вкладе Images.

Теперь создаём Docker контейнер на основе образа.

make docker-container

В результате создаётся контейнер с названием compthermobook. Проверьте Docker Desktop, во вкладе Containers он должен появиться.

Запустите контейнер командой.

make docker-container-start

И попробуйте к нему подключиться (используется bash оболочка).

make docker-container-inspect

В этом контейнере вы root пользователь и по умолчанию попадаете в домашнюю директорию пользователя --- /root/. Можете попробовать запустить Python командой python3 или Julia командной julia.

Чтобы отключиться из контейнера, введите exit или Ctrl+D. Отключитесь от контейнера.

Изменение материалов книги и создание новых

Базовый шаблон работы с книгой следующий.

1. Вы запускаете Docker Desktop и контейнер make docker-container-start.
2. Вы вносите изменения в исходный код книги (book/).
3. Сохраняете изменения.
4. Затем пользуетесь make командами html, html-all, html-clean, html-clean-all.

Контейнер настроен так, что содержимое директории book/ синхронизировано с директорией /root/book/ в контейнере. Когда вы сохраняете изменения, они появляются и в контейнере, и наоборот. При использовании make команд в контейнер отправляются на исполнение команды для создания веб-файлов книги. Веб-файлы (компиляция книги для веба из исходников) располагаются по умолчанию в book/_build/html (и в /root/book/_build/html в контейнере).

Первое создание книги может длиться долго, поскольку jupyter-book будет исполнять код из материалов книги.

Чтобы создать книгу в первый раз, воспользуйтесь.

make html

Проверьте, что локально появилась директория book/_build/html. Можете открыть страницу book/_build/html/index.html в браузере для проверки.

Локальной версией не всегда удобно пользоваться, поэтому можете создать сервер командой.

make local-server

Сервер запустится в контейнере, а открыть книгу можно в браузере по адресу http://localhost:8080/.

Публикация книги и изменений

Для публикации веб-версии книги используется сервис GitHub Pages. Адрес (index страницы) онлайн-книги имеет вид

  https://<username or orgname>.github.io/<repository name>/
( https://stepanzh.github.io/computational_thermodynamics/   )

По умолчанию для публикации в GitHub Pages используется ветка репозитория gh-pages. Всё, что в ней расположено, воспринимается как статический сайт, поэтому нужно очистить ветку и поместить туда содержимое book/_build/html/.

Однако вручную это делать неудобно. Лучше воспользоваться Python утилитой ghp-import https://github.com/ionelmc/python-ghp-import, которая стандартно устанавливается.

Кроме того, Makefile добавлена команда

make github-pages

которая использует ghp-import и отправляет на публикацию материалы из book/_build/html/.

Перед публикацией материалов проверьте как выглядит книга. Также желательно перед публикацией выполнить

make html-clean
make html-all

Первая команда стирает веб-версию книги (но оставляет кэш из материалов, созданных программно), а вторая создаёт книгу.

Именование версий книги

При накоплении большого числа изменений добавьте git tag (и, возможно, release).

Поскольку курс читается раз в год, то за основу имени версии берётся

vГОД.MAJOR.MINOR

где

• ГОД >= 2023 это год преподавания, к которому относится изменение. Т.е. если какой-то материал читался в 2022 году, но был оцифрован и попал в книгу в 2023 (например, в январе), то ГОД считается 2022-ым.
• MAJOR >= 0 касается крупных изменений. Например,
  • добавление новой темы (одна страница, целый раздел),
  • изменение оглавления,
  • обновление Python или Julia библиотек для книги (файлы requirements),
  • накопление большого количества мелких исправлений.
• MINOR >= 0 касается мелких изменений. Например, исправление опечатки, переписывание абзаца, исправление битой ссылки.

Исключение представляет версия v2023.0.0, поскольку она начальная. Фактически, в неё был включён материал, преподававшийся годами ранее, но оставленный для заинтересованных читателей.

Обзор make команд

Полное описание команд располагается (sic!) в Makefile.

help

Показать это сообщение с помощью.

html

Создать веб-версию книги или обновить изменённые страницы.

html-all

Создать веб-версию книги с принудительной сборкой всех страниц.

html-clean

Очистить директорию с веб-версией книги, но оставить jupyter-book кэш.

html-clean-all

Очистить директорию с веб-версией книги, включая jupyter-book кэш.

github-pages

Опубликовать веб-версию книги, используя GitHub Pages.

docker-image

Создать Docker образ для работы с книгой.

docker-container

Создать Docker контейнер на основе образа для работы с книгой.

docker-container-start

Запустить Docker контейнер.

docker-container-stop

Остановить работу Docker контейнера.

docker-container-inspect

Подключиться к контейнеру (bash оболочка).

local-server

Запустить локальный сервер в контейнере.

Команды docker-image и docker-container используются только при первом создании книги.

При правильной установке базовый шаблон работы следующий.

• Запускаете Docker Desktop.
• make docker-container-start local-server.
• Вносите изменения в материалы или добавляете новые.
• make html или make html-all
• Проверяете материалы.
• Делаете commit в репозиторий.
• Публикуете материалы make github-pages.
• Отключаете контейнер make docker-container-stop.

Вопрос-ответ

Какие Python и Julia пакеты доступны для генерации веб-файлов книги?

Те, что перечислены python-requirements.txt и julia-requirements.toml, соответственно.

Для создания материалов книги мне нужен Julia пакет, которого нет в контейнере. Как его установить?

Для тестирования запустите контейнер и подключитесь к нему make docker-container-start docker-container-inspect. В контейнере запустите Julia REPL и установите пакет в глобальное окружение как обычно ((v1.9) pkg> add).

Если пакет нужен и в будущем, добавьте его в julia-requirements.toml, пересоберите Docker образ и создайте новый контейнер на его основе. В новом образе пакет будет включён.

Как обновить версию пакета для создания книги?

См. предыдущий вопрос. Все действия те же, но проверьте, как много новая версия пакета (например, jupyter-book) ломает существующие материалы. Может, игра не стоит свеч.

Я добавил(а) новую страницу (или раздел) в книгу, но он не отображается в навигацианной панели в веб-версии книги.

Проверьте, что вы не забыли включить новую страницу в book/_toc.yml. Затем, вместо make html используйте make html-all. Последняя команда запускает jupyter-book build с опцией --all, которая отвечает за сборку всех страниц книги, а не только тех, в которых появились изменения.

Я обновил(а) изображение для материалов книги, но в веб-версии книги показывается старая версия изображения.

Используйте make html-all вместо make html. Версия html-all скопирует новую версию изображения (ту, что в исходных файлах) взамен старой (той, что в book/_build/html/).

Зачем понадобился Docker?

Для создания книги используется Python, jupyter, jupyter-book и Julia, одним словом, зоопарк технологий (скромный, но зоопарк). Такому набору инструментов нужно окружения для кроссплатформенности разработки, но virtualenv не хватало. Поэтому проще оказалось создать Docker контейнер.