рабочему процессу и определяем, когда он должен запускаться. Поскольку ваша документация является общедоступной, вы не захотите, чтобы она обновлялась с возможными критическими изменениями каждый раз, когда что-то объединяется. Вместо этого мы настраиваем этот рабочий процесс для запуска при создании новой версии, чтобы документация всегда соответствовала последней версии. стабильный релиз проекта.
Поэтапно мы проверяем код, устанавливаем Crystal, создаем документацию, запуская crystal docs, и, наконец, загружаем документацию на GitHub Pages.
Мы используем внешнее действие для развертывания документации. Есть немало других действий, которые поддерживают это, или вы также можете сделать это вручную, но я обнаружил, что это работает довольно хорошо и его легко настроить. Вы можете проверить https://github.com/JamesIves/github-pages-deploy-action для получения дополнительной информации об этом действии.
Мы предоставляем несколько вариантов конфигурации для действия. Первые два являются обязательными и указывают, в какую ветку нашего репозитория следует загрузить документацию, а второй представляет источник документации для загрузки. В качестве названия ветки вы можете выбрать все, что захотите. Я просто назвал его gh-pages, чтобы было понятно, для чего он используется.
Кроме того, поскольку Crystal Docs выводит результаты в папку docs/, я указал ее в качестве исходной папки. Я также устанавливаю для опции single-commit значение true. По сути, это сбрасывает историю нашей ветки, так что в этой ветке всегда остается только один коммит. В нашем случае это нормально, поскольку при необходимости документацию можно легко восстановить, поэтому нет необходимости хранить эту историю.
На этом этапе определены все наши рабочие процессы. Рабочий процесс CI гарантирует, что код, поступающий в проект, действителен и работает должным образом, а рабочий процесс развертывания развернет нашу документацию на страницах GitHub при создании нового выпуска. Как только это произойдет, вы сможете перейти к URL-адресу страниц вашего репозитория, чтобы увидеть результаты.
Вы также можете добавить дополнительные элементы в рабочий процесс развертывания, например автоматическое создание/публикацию двоичных файлов выпуска.
И вот оно! Непрерывная интеграция может быть отличным способом более легкого управления вкладами, поскольку у вас есть автоматизированный способ, который может обеспечить соблюдение ваших стандартов и упростить отладку/уведомление о любых возникающих проблемах. Это также может помочь автоматизировать процесс развертывания. Он также настраиваемый и достаточно гибкий, чтобы справиться практически с любым вариантом использования.
Еще раз поздравляю с завершением книги! В различных областях Crystal было много контента, который, мы надеемся, предоставил некоторую полезную информацию, которую можно будет использовать в ваших будущих проектах или, еще лучше, послужить справочной информацией по некоторым более сложным темам.
Приложение A. Настройка инструмента
Компилятор Crystal отвечает за анализ кода Crystal и создание исполняемых файлов для отладки и выпуска. Обычный процесс написания кода, а затем использование компилятора для сборки и запуска вашего приложения может быть полностью выполнен с использованием интерфейса командной строки, но он быстро становится утомительным.
Это приложение научит вас настраивать и использовать Crystal из Visual Studio Code со стандартными функциями IDE, такими как подсветка синтаксиса, завершение кода, наведение курсора на символы для получения дополнительной информации, изучение классов и методов, определенных в файле, сборка проекта и запустить его. Если вы используете другие редакторы кода, инструкции должны быть аналогичными.
Установка компилятора Crystal
Первый шаг — убедиться, что компилятор Crystal установлен правильно. Попробуйте запустить команду crystal --version со своего терминала. Вы можете перейти к следующему разделу, если он успешно показывает версию компилятора и целевую архитектуру.
Перейдите на https://crystal-lang.org/install и проверьте точные инструкции для вашей операционной системы. В macOS Crystal доступен на сайте Homebrew. В большинстве дистрибутивов Linux Crystal доступен из репозитория. Crystal также доступен для систем BSD.
Установка компилятора в Windows
В Windows компилятор Crystal все еще находится в экспериментальной стадии (начиная с Crystal 1.4.0). Итак, вы должны включить подсистему Windows для Linux (WSL) и использовать дистрибутив Linux внутри Windows.
Если вы еще не использовали WSL, включить его очень просто. Вам потребуется либо Windows 10, либо Windows 11. Откройте Windows PowerShell, выберите «Запуск от имени администратора» и выполните команду wsl --install.
Рисунок 18.1 - Запуск PowerShell от имени администратора
По умолчанию он будет использовать WSL2 с Ubuntu, как показано на следующем снимке экрана. Это хороший вариант по умолчанию, если вы раньше не использовали Linux:
Рисунок 18.2 - Включение WSL
После выполнения этих шагов приступайте к установке Crystal внутри WSL, используя инструкции Ubuntu с официального сайта, как упоминалось ранее.
Установка кода Visual Studio
Если у вас нет Visual Studio Code, вы можете установить его с официального сайта https://code.visualstudio.com/. Это популярный, бесплатный и мощный редактор кода.
Если вы используете Windows и WSL, то установите расширение Remote — WSL. Это позволит Visual Studio Code подключаться к WSL.
Рисунок 18.3 - Установка расширения Remote – WSL
После установки этого расширения вы увидите небольшой зеленый значок в левом нижнем углу экрана. Используйте его, чтобы открыть окно WSL.
Рисунок 18.4 - Использование расширения редактора
Найдите и установите расширение Crystal Language с помощью языковых инструментов Crystal.
Рисунок 18.5 - Установка расширения Crystal Language
Он предоставит вам подсветку синтаксиса, форматирование кода и структуру проекта.
Рисунок 18.6 – Включение языкового сервера Crystalline
Чтобы раскрыть весь потенциал расширения, ему также необходим языковой сервер. Мы рекомендуем использовать для этого Crystalline. Это позволит завершить код, сообщить об ошибках, перейти к определению и получить информацию о символе при наведении курсора мыши.
Инструкции по установке можно найти по адресу https://github.com/elbywan/crystal#pre-built-binaries. По ссылке показана команда для загрузки и установки на macOS и Linux. Если вы используете Windows, следуйте инструкциям Linux внутри WSL.
Чтобы включить некоторые дополнительные функции, перейдите в настройки кода Visual Studio (Файл | Настройки | Settings) и найдите Crystal. Вы можете включить больше или меньше функций, но имейте в виду, что анализ кода Crystal не является легким процессом и может быть медленным для более крупных проектов в зависимости от вашего компьютера:
1. Первые параметры включают завершение кода, наведение курсора мыши и функцию перехода к определению; включите их.
Рисунок 18.7 - Дополнительные
