Перейти к содержанию

Руководство для контрибьюторов

Привет! Здорово, что вы решили внести свой вклад в улучшение нашей документации. В этом гайде мы объясним, как легко и быстро присоединиться к разработке.

Если вы уже работали с git и участвовали в opensource проектах – вам будет легко разобраться. Но всё равно рекомендуем пробежаться по гайду, здесь есть важные особенности нашего процесса разработки.

А если вы новичок, этот гайд станет отличной отправной точкой в изучении такого мощного и полезного инструмента как git.

С чего начать

Документация REDKit размещена на GitHub и собирается с помощью Material for MkDocs.

Вот простые шаги, чтобы присоединиться к разработке:

  1. Если у вас еще нет аккаунта GitHub, зарегистрируйтесь.
  2. Перейдите в репозиторий документации REDKit.
  3. Нажмите на кнопку "Fork" в правом верхнем углу, чтобы создать свою копию репозитория.

Форматирование текста

Мы используем markdown для оформления документации – это простой и удобный язык разметки. Основы можно освоить за 5 минут, прочитав краткий гайд.

Благодаря Material for MkDocs, кроме стандартного Markdown мы можем использовать дополнительные фишки: вкладки, спойлеры, заметки и многое другое. Подробнее – в официальной документации

Совет

В блоках кода можно использовать язык Witcher Script. Для него есть подсветка синтаксиса. Укажите язык как "witcherscript" или "ws".

Как вносить изменения

Через веб-интерфейс GitHub

Для небольших правок удобно использовать веб-интерфейс GitHub:

  1. Найдите файл, который нужно отредактировать
  2. Нажмите на иконку карандаша (Edit this file)
  3. Внесите необходимые изменения в Markdown-редакторе
  4. Нажмите на кнопку "Commit changes"
  5. Напишите краткое описание ваших изменений
  6. Выберите "Create a new branch for this commit and start a pull request"
  7. Нажмите "Propose changes"

Продвинутый способ: работа локально

Для серьезных изменений лучше работать на своем компьютере. Вот что вам понадобится:

Необходимые инструменты:

  1. Git
  2. Python 3.12
  3. Visual Studio Code (рекомендуемый редактор с полезными расширениями)
    • Установите полезные расширения для работы с Markdown:
      1. "Markdown All in One" - делает редактирование удобнее
      2. "Markdown Preview Enhanced" - позволяет видеть, как будет выглядеть результат

Настройка окружения

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Выберите папку для проекта
cd путь/к/папке

# Склонируйте ВАШ форк
git clone https://github.com/ваш-никнейм/docs.git
cd docs

# Установите необходимые пакеты
pip install -r requirements.txt

# Создайте новую ветку для ваших изменений
git checkout -b имя-ветки

Процесс работы

  1. Откройте проект в VS Code.
  2. Запустите локальный сервер командой mkdocs serve или mkdocs serve -f mkdocs.en.yml для английской версии.
  3. Просматривайте изменения в реальном времени по адресу http://127.0.0.1:8000

После внесения изменений:

Bash
1
2
3
4
5
6
7
8
# Добавьте измененные файлы в Git
git add .

# Создайте коммит с описанием изменений
git commit -m "Описание ваших изменений"

## Отправьте изменения в ваш форк
git push origin имя-ветки

Совет

В VS Code есть удобный интерфейс для работы с Git – найдете его во вкладке Source Control ( Ctrl+Shift+G )

Синхронизация форка

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

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Добавьте основной репозиторий как удаленный источник (делается один раз)
git remote add upstream https://github.com/redkit-resources/docs.git

# Получите изменения из основного репозитория
git fetch upstream

# Переключитесь на main ветку
git checkout main

# Примените изменения из основного репозитория
git merge upstream/main

# Отправьте обновления в ваш форк
git push origin main

# Переключитесь на вашу ветку для изменений
git checkout имя-ветки

# Примените изменения из main
git merge main

# Разрешите конфликты, если они возникли

Создание Pull Request

  1. Откройте ваш форк на GitHub
  2. Нажмите "Compare & pull request"
  3. Проверьте что:
    • Заголовок понятно объясняет, что вы сделали
    • В описании есть подробности о ваших изменениях
    • Выбрана ветка main

Изображения

Важно

Давайте сделаем сайт быстрее и сэкономим место! Используйте современные форматы изображений!

WEBP – является самым прогрессивным форматом хранения изображений на сегодня. Просьба использовать WEBP вместо JPEG или PNG.

Сжать и конвертировать можно как в любом онлайн-конвертере, так и воспользоваться нашим, очень простым конвертером.

Краткий гайд по использованию:

Bash
1
2
3
4
5
# Перейдите в папку проекта, если вы ещё не в ней
cd /путь/к/папке

# Сконвертируйте изображение (поддерживает почти все форматы)
python conv.py -i "docs/assets/images/путь/к/изображению.png"

Скрипт автоматически заменит ваш файл на сконвертированный в webp

Как добавить изображения:

  1. Сохраните файлы в docs/assets/images/
  2. Ссылайтесь на них относительными путями:
Markdown
![Описание изображения](../assets/images/example.webp)

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

Видео

Видео лучше не загружать прямо в документацию.

Используйте YouTube:

  1. Загрузите видео на YouTube
  2. Нажмите "Поделиться" → "Встроить"
  3. Скопируйте код и вставьте его в документ

Теперь вы полностью готовы стать частью нашей команды! 👏