Соскучились? Отдохнули? Я и соскучился, и отдохнул, и набрался сил для второй части курса 🧑🎓
Рад снова всех видеть и рад продолжить наши docs-as-code встречи)
Сегодня мы установим генератор статических сайтов.
Итак, в прошлый раз мы выбрали MkDocs. Это популярный, современный генератор, в котором легко и удобно работать.
Для установки мы будем пользоваться Python installs Packages (pip) — пакетным менеджером python. Если вы всё сделали правильно, pip уже есть на вашем компьютере (он идёт в одном дистрибутиве вместе с самим пайтоном).
1. Установите генератор MkDocs. Для этого откройте CMD и выполните команду:
pip install mkdocs
2. Мы будем использовать не простой MkDocs, а одну из самых популярных его тем — MkDocs material theme. Установите её на компьютер с помощью команды:
pip install mkdocs-material
Поздравляю! Необходимые инструменты настроены. Теперь нам нужно настроить наш проект. В MkDocs вы можете создать конфигурационный файл автоматически с помощью команды
mkdocs new название_папки_проекта, но в таком случае будет создан не только конфиг, но и папка для проекта с файлом index.md, что для нас уже лишнее. Поэтому мы займёмся ручной настройкой структуры и конфигурации нашего проекта.1. Перейдите в папку с репозиторием проекта с помощью команды
cd путь_к_папке;2. Проверьте состояние проекта с помощью команды
git status. Убедитесь, что вы находитесь в главной ветке. Если нет, переключитесь на неё (команда git switch main);3. Обновите репозиторий с помощью команды
git pull;4. Отколите новую ветку, в которой вы будете совершать настройку проекта. По нашему устоявшемуся стайлгайду можете назвать её task-2-setup-mkdocs;
5. Откройте папку проекта через проводник;
6. В папке создайте файл
mkdocs.yml. Это конфиг, с помощью которого мы будем управлять нашей документацией;7. Приведите структуру проекта к шаблону:
├─ docs/
│ └─ index.md
└─ mkdocs.yml
По шаблону все исходники должны лежать в подпапке docs. Создайте папку docs и перенесите туда файл index.md;
8. Откройте файл mkdocs.yml (с помощью VS Code или любого другого редактора кода) и добавьте туда название вашего проекта:
site_name: Parawriter docs
9. Сохраните изменения в mkdocs.yml и закройте файл.
Теперь проверим, что наш генератор работает, и запустим локальную сборку сайта. Для этого в консоли выполните команду
mkdocs serve. Если всё сделано правильно, в ответ придёт адрес локального порта, на котором собралась ваша дока:C:\Users\User1\parawriter\parawriter_docs>mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.11 seconds
INFO - [11:59:50] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [11:59:50] Serving on http://127.0.0.1:8000/
Если вы перейдёте по адресу в последней строке, то сможете посмотреть как будет выглядеть ваш сайт. Не переживайте, мы сделаем его лучше и красивее).
Теперь дело за малым: закоммитьте изменения, отправьте их на сервер, создайте пул-реквест и влейте рабочую ветку в ветку main. Подробности процесса описаны в наших прошлых уроках: здесь и здесь.
В следующий раз мы займёмся настройкой внешнего вида проекта с помощью конфига mkdocs.yml
P.S. Если вы столкнулись с проблемами на этом этапе, приходите в комментарии, я постараюсь помочь 🛠
#практика #docsascode