Система контроля версий#

Система контроля версий (git) — это система, записывающая изменения в файл или набор файлов в течение времени и позволяющая вернуться позже к определённой версии.

Конкретно в нашем случае эта система поможет поддерживать документацию в актуальном виде, работать с помощью неё в команде и публиковать её на ReadTheDocs.

Первые шаги#

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

После этого зарегистрируйтесь на GitHub.

Attention

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

После регистрации необходимо создать репозиторий:

  1. Нажмите на кнопку New.

  2. В появившемся окне введите название репозитория.

  3. Нажмите Create repository.

.gitignore#

Перед тем, как залить исходники на github, нам надо создать файл, который будет избавлять наш репозиторий от мусора: временные файлы, файлы сборки, повторяющиеся медиафайлы, venv и прочее.

В папке с сайтом создайте файл с именем .gitignore и скопируйте туда следующие наименования:

venv/
*.mo
build/
.vscode/
*.log

Если не вдаваться в подробности, то это те файлы, которые нужны либо только на конкретно вашем компьютере, либо файлы сборки.

Как опубликовать сайт, без файлов сборки, я расскажу в следующем пункте.

SSH#

Возможно эта тема покажется сложнее, чем предыдущие, но для удобства нам понадобится сгенерировать SSH-ключ. С помощью него вы сможете без ввода пароля публиковать свою документацию на github.

Откройте терминал и введите команду:

ssh-keygen

После этого выйдут два запроса, на которые можно просто нажимать Enter:

  1. В первом он запросит название файла для ключа — по умолчанию он его назовёт id-rsa.

  2. Во втором он предложит сделать дополнительный пароль для защиты ключа — по умолчанию пароль не будет задан.

Потом перейдите в папку .ssh с помощью команды:

cd .ssh

Если вы не меняли название файла при создании, то в этой папке лежит файл id-rsa.pub. Если переименовали, то в любом случае необходимо открыть тот файл, у которого расщирение будет .pub. Введите команду:

cat id-rsa.pub

Скопируйте весь код, который появился в окне терминала, и введите его в SSH форму в настройках профиля на Github.

Инициализация#

После этого перейдите в терминал в VS Code и последовательно введите следующие команды по очереди:

git init

git add .

git commit -m “init”

git branch -m main

git remote add origin git@github.com:[ИмяВашегоАккаунта]/[название-вашего-репозитория].git

git push -u origin main

  1. Первой командой вы инициализируете систему контроля версий.

  2. Далее вы трекаете все файлы, которые находятся в папке и не занесены в .gitignore. Тут точка означает путь к файлам.

  3. Здесь вы создаёте первый коммит.

  4. Тут создаётся главная (main) ветка.

  5. Здесь вы привязываетесь к удалённому репозиторию на вашем GitHub аккаунте.

  6. Последней командой вы отправляете данные в ваш удалённый репозиторий.