Привет!

Рад пригласить вас на последние уроки курса «Docs-as-code для самых маленьких»!
Сегодня мы настроим выгрузку нашего сайта на GitHub Pages.
GitHub Pages — это сервис от GitHub, с помощью которого можно бесплатно опубликовать свой сайт на домене your_name.github.io/name_repo.
Выполнить публикацию вручную очень легко:
1. Откройте CMD;
2. Зайдите в папку с проектом, используя команду cd;
3. Убедитесь, что вы находитесь в ветке main и что все изменения собраны в коммиты и залиты в main;
4. Выполните команду для сборки и публикации сайта:

mkdocs gh-deploy

Всё получилось! MkDocs преобразует ваши исходники в html, с помощью скрипта ghp-import фиксирует изменения в ветке gh-pages и отправляет их в GitHub.
GitHub автоматически публикует собранный сайт из ветки gh-pages на GitHub Pages.
Если процесс прошёл без ошибок, в ответе на команду mkdocs gh-deploy отобразится URL вашего сайта:

<…>
To https://github.com/novillero/parawriter_docs.git
 * [new branch]      gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://novillero.github.io/parawriter_docs/

Теперь давайте посмотрим на настройки в Гитхабе:

1. Откройте свой репозиторий в гитхабе и перейдите на вкладку Settings;
2. В левом меню выберите пункт Pages;
3. На этой странице указаны настройки публикации сайта на GitHub Pages. Посмотрите на установленные значения:
Sourse — Deploy from a branch;
Branch — gh-pages; folder — /(root).
Это значит, что ваш сайт публикуется из ветки, ветка для публикации — gh-pages.

А теперь откройте вкладку Actions. Здесь отображаются все запущенные workflow публикации вашего сайта. Каждый раз, когда вы запускаете сборку командой mkdocs gh-deploy, в разделе Actions → All workflow появляется новая запись. Нажмите на запись, чтобы увидеть подробности сборки и ссылку на опубликованный сайт. Зелёная галочка сообщает о том, что процесс прошёл удачно и сайт опубликован. Красный крестик показывает, что сборка и публикация завершились ошибкой. В этом случае стоит проверить валидность конфига и файлов проекта. Делается это очень просто с помощью команды mkdocs build. MkDocs проверит, можно ли собрать сайт, и отобразит лог ошибок и предупреждений. Я рекомендую выполнять эту команду каждый раз перед тем, как запустить сборку и публикацию сайта.
UPD: прошу прощения, что ввёл в заблуждение. Команда mkdocs build генерирует статические html-файлы на основе ваших исходников и выполняется уже непосредственно при деплое проекта. Ошибки и предупреждения вы можете посмотреть с помощью команды mkdocs serve — все они отобразятся в командной строке. Я не рекомендую выполнять mkdocs build для проверки валидности сборки, так как в результате создаётся папка site с html-файлами, которая нам не нужна.

Поздравляю! Главная цель достигнута — сайт с документацией опубликован. Теперь вы можете каждый раз после обновления проекта (вливания рабочей ветки в main) запускать пересборку и публикацию изменений. Казалось бы, всё прекрасно! Но в настоящем docs-as-code сборка и публикация документации должны происходить автоматически. Поэтому в следующий раз мы с вами попробуем настроить процесс CI (автоматические сборка и деплой доки), который будет запускаться после каждого обновления главной ветки main.

Традиционно жду ваши вопросы в комментариях! 🧑‍🎓

#практика #docsascode