Создание Jupyter Book v1 для GitHub Pages

Создание Jupyter Book в формате v1 без MyST для развертывания на GitHub Pages возможно через использование ветки v1 репозитория Jupyter Book, которая основана на Sphinx вместо MyST. Для этого необходимо скачать соответствующую ветку, установить зависимости, создать структуру курса и выполнить сборку в HTML и PDF форматы, после чего развернуть полученные файлы на GitHub Pages через специальную ветку gh-pages.

Содержание

• Введение в Jupyter Book v1
• Установка и настройка Jupyter Book v1
• Создание структуры книги для университетских курсов
• Генерация HTML и PDF без MyST
• Развертывание на GitHub Pages
• Решение распространенных проблем

Введение в Jupyter Book v1

Jupyter Book v1 — это версия инструмента для создания интерактивных учебных материалов, которая не использует MyST (Markedly Structured Text) в отличие от более новых версий. Для университетских курсов эта версия предпочтительна, так как она генерирует стандартные HTML и PDF файлы, готовые для развертывания на GitHub Pages.

Важное отличие версии 1 от современных версий заключается в том, что она полностью основана на Sphinx — мощном инструменте для создания документации. Это означает, что вы можете использовать обычные Jupyter-ноутбуки и Markdown файлы без необходимости изучать синтаксис MyST. Для образовательных проектов, где важна совместимость и простота развертывания, jupyter книга в формате v1 остается отличным выбором.

При работе с университетскими материалами вы сможете создавать структуру, включающую лекции, лабораторные работы, задания и учебные пособия — все в едином формате, который легко публикуется и доступен студентам через GitHub Pages.

Установка и настройка Jupyter Book v1

Для начала работы с Jupyter Book v1 необходимо установить правильную версию из репозитория. В отличие от стандартной установки через pip, для получения версии v1 нужно использовать ветку репозитория на GitHub.

Шаг 1: Установка Jupyter Book v1

# Установка через pip (получится последняя версия)
pip install jupyter-book

# Но для версии v1 лучше скачать репозиторий
git clone https://github.com/executablebooks/jupyter-book.git
cd jupyter-book
git checkout v1
pip install -e .

Этот подход гарантирует, что вы используете именно версию 1, которая не требует MyST и основана на Sphinx. После установки вы сможете использовать команду jupyter-book в командной строке.

Шаг 2: Создание нового проекта

# Создание новой книги Jupyter Book v1
jupyter-book create my_course
cd my_course

Эта команда создаст структуру проекта с основными директориями и файлами конфигурации. В отличие от версии 2, здесь не будет MyST-специфичных файлов, что упрощает работу с обычными Markdown и Jupyter-ноутбуками.

Шаг 3: Настройка конфигурации

Откройте файл _config.yml и настройте параметры книги:

title: "Мой университетский курс"
author: "Ваше имя"
logo: "path/to/logo.png"

Для github pages развертывание также рекомендуется добавить:

sphinx:
 config:
 html_theme: 'sphinx_book_theme'
 html_static_path: ['_static']

Создание структуры книги для университетских курсов

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

Базовая структура проекта

my_course/
├── _config.yml # Конфигурация книги
├── _toc.yml # Оглавление
├── index.md # Главная страница
├── lectures/ # Папка с лекциями
│ ├── intro.md
│ └── advanced.md
├── labs/ # Папка с лабораторными работами
│ ├── lab1.ipynb
│ └── lab2.ipynb
├── assignments/ # Папка с заданиями
│ └── assignment1.md
└── _build/ # Сгенерированные файлы (создается при сборке)

Создание оглавления (_toc.yml)

Файл _toc.yml определяет структуру книги:

- file: index
- part: Введение
 chapters:
 - file: lectures/intro
 - file: lectures/advanced
- part: Лабораторные работы
 chapters:
 - file: labs/lab1
 - file: labs/lab2
- part: Задания
 chapters:
 - file: assignments/assignment1

Работа с содержимым

Для лекций используйте Markdown файлы с поддержкой математических формул:

# Лекция 1: Основы программирования

Пример математической формулы:
$$E = mc^2$$

## Пример кода

```python
def hello_world():
 print("Hello, World!")
 return "Success"

Для интерактивных элементов используйте Jupyter-ноутбуки (.ipynb файлы), которые позволят включать исполняемый код, графики и визуализации прямо в учебные материалы.

---

## Генерация HTML и PDF без MyST {#generating-html-and-pdf-without-myst}

Одна из главных задач при создании jupyter книги — это генерация файлов в форматах, подходящих для публикации. В версии v1 Jupyter Book предоставляет простые команды для создания как HTML, так и PDF версий без необходимости использовать MyST.

### Сборка HTML версии

```bash
# Генерация HTML версии
jupyter-book build my_course

Эта команда создаст директорию _build/html со всеми необходимыми файлами для публикации в интернете. HTML версия включает навигацию, поиск и интерактивные элементы.

Сборка PDF версии

Для генерации PDF потребуется дополнительный шаг:

# Сначала генерируем HTML
jupyter-book build my_course

# Затем конвертируем в PDF
cd _build/html
make latexpdf

Процесс конвертации в PDF может занять некоторое время, так как включает генерацию LaTeX документов. Если у вас возникнут проблемы с LaTeX, установите необходимые пакеты:

# Ubuntu/Debian
sudo apt-get install texlive-full

# macOS
brew install --cask mactex

Проверка результатов

После сборки проверьте директорию _build/html:

• index.html — главная страница
• _static/ — стили и изображения
• part1/, part2/ — главы книги

Для PDF файла проверьте _build/_latex/my_course.pdf.

Развертывание на GitHub Pages

После генерации HTML и PDF файлов необходимо развернуть их на GitHub Pages. Это позволит сделать ваш университетский курс доступным для студентов через интернет.

Подготовка репозитория

1. Создайте новый репозиторий на GitHub
2. Загрузите содержимое вашей книги:

git init
git add .
git commit -m "Initial commit: Jupyter Book v1"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Создание ветки для GitHub Pages

GitHub Pages требует размещения файлов в специальной ветке:

# Создаем ветку gh-pages
git checkout --orphan gh-pages
git rm -rf .
git add _build/html/
git commit -m "Add Jupyter Book for GitHub Pages"
git push -u origin gh-pages

Настройка GitHub Pages

1. Перейдите в настройки вашего репозитория на GitHub
2. В разделе “Pages” выберите ветку “gh-pages” и папку “/ (root)”
3. Нажмите “Save”

После этого ваш курс будет доступен по адресу: https://yourusername.github.io/your-repo

Автоматизация развертывания

Для автоматической пересборки при изменениях можно использовать GitHub Actions. Создайте файл .github/workflows/deploy.yml:

name: Deploy Jupyter Book

on:
 push:
 branches: [main]

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - name: Build Jupyter Book
 run: |
 pip install jupyter-book
 jupyter-book build my_course
 - name: Deploy to GitHub Pages
 uses: peaceiris/actions-gh-pages@v3
 with:
 github_token: ${{ secrets.GITHUB_TOKEN }}
 publish_dir: ./_build/html

Решение распространенных проблем

При работе с Jupyter Book v1 вы можете столкнуться с несколькими типичными проблемами, особенно при развертывании на GitHub Pages.

Проблема 1: Ошибки при установке

Симптом: pip install jupyter-book устанавливает версию 2.x вместо v1
Решение: Используйте установку из репозитория:

pip uninstall jupyter-book
git clone https://github.com/executablebooks/jupyter-book.git
cd jupyter-book
git checkout v1
pip install -e .

Проблема 2: Отсутствие поддержки LaTeX в Windows

Симптом: Ошибка при генерации PDF из-за отсутствия LaTeX
Решение: Установите MiKTeX для Windows или используйте онлайн-конвертер:

# Альтернативный способ генерации PDF
jupyter-book build my_course
cd _build/html
pip install weasyprint
weasyprint index.html my_course.pdf

Проблема 3: Проблемы с GitHub Pages

Симптом: Сайт не загружается или отображается некорректно
Решение:

1. Убедитесь, что файлы находятся в ветке gh-pages
2. Проверьте путь к файлам в настройках Pages
3. Очистите кэш браузера
4. Убедитесь, что в HTML нет относительных путей к изображениям

Проблема 4: Конфликты версий зависимостей

Симптом: Ошибки совместимости пакетов
Решение: Используйте виртуальное окружение:

python -m venv jbook_env
source jbook_env/bin/activate # Linux/macOS
# или
jbook_env\Scripts\activate # Windows
pip install jupyter-book

Проблема 5: Медленная загрузка больших книг

Симптом: GitHub Pages долго загружает большие книги
Решение: Оптимизируйте книгу:

1. Используйте легкие изображения
2. Разделяйте большие главы на несколько файлов
3. Минимизируйте количество исполняемых ячеек в Jupyter-ноутбуках

Источники

1. Jupyter Book v1 Documentation — Официальная документация версии Jupyter Book v1 без MyST: https://github.com/executablebooks/jupyter-book/tree/v1
2. GitHub Pages Deployment Guide — Инструкция по развертыванию статических сайтов на GitHub Pages: https://pages.github.com/
3. Sphinx Documentation — Документация Sphinx, на котором основан Jupyter Book v1: https://www.sphinx-doc.org/
4. Jupyter Book GitHub Repository — Основной репозиторий проекта Jupyter Book: https://github.com/executablebooks/jupyter-book
5. GitHub Actions Documentation — Документация по автоматизации развертывания с GitHub Actions: https://docs.github.com/en/actions

Заключение

Создание Jupyter Book в формате v1 для развертывания на GitHub Pages — это надежный способ публикации университетских курсов в интернете. Используя ветку v1 репозитория, вы можете создавать структурированные учебные материалы на основе Sphinx без необходимости изучать MyST-синтаксис.

Ключевые преимущества подхода включают генерацию стандартных HTML и PDF файлов, простую навигацию по курсу и возможность автоматического развертывания через GitHub Pages. Для преподавателей это означает возможность создавать профессионально выглядящие учебные материалы без сложной технической настройки.

Следуя изложенным шагам — от установки и настройки до генерации файлов и развертывания — вы сможете создать полноценный университетский курс, доступный студентам в любое время и в любом месте. github pages развертывание таких книг обеспечивает высокую доступность и удобство использования для образовательных целей.