Установка Собираки в Ubuntu

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

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

1. Установка Python #

Для запуска Собираки потребуется Python версии 3.11 или выше. На момент написания инструкции актуальная версия 3.13, она тоже подходит.

Откройте окно командной строки и введите следующую команду:
```
sudo apt install python3 --yes
```
Впрочем, скорее всего, программа завершится мгновенно, так как в современных версиях Ubuntu сразу предустанавливаются современные версии Python.
Чтобы проверить установку, откройте окно командной строки и введите следующую команду.
```
python --version
```
Появится текст наподобие Python 3.13. Если версия не ниже 3.11, значит, всё отлично.

2. Установка Pandoc #

Pandoc — необходимый инструмент, без которого Собирака не может работать. Корректная работа Собираки проверена с версиями Pandoc от 3.3 до 3.7. У других версий могут отличаться внутренние форматы данных, и Собирака может их не понимать.

Скачайте пакет Pandoc: pandoc-3.7-1-amd64.deb.
Откройте окно командной строки и перейдите в директорию, в которую вы сохранили пакет. Например:
```
cd /home/user/Downloads
```
Выполните следующую команду:
```
sudo dpkg -i pandoc-3.7-1-amd64.deb
```
Чтобы проверить установку, откройте окно командной строки и введите следующую команду:
```
pandoc --version
```
Появится текст, начинающийся со строчки pandoc 3.7.

3. Подготовка окружения #

Чтобы Собирака и требуемые для неё пакеты не мешали другим проектам на Python, которые могут оказаться на вашем компьютере сейчас или в будущем, мы создадим отдельное виртуальное окружение Python. Позже мы установим Собираку внутри этого окружения.

Всё виртуальное окружение будет храниться в одной папке. Часто для этой цели создают поддиректорию под названием venv в папке с документацией. Но это необязательно. Можно выбрать для папки другое название или разместить её в другом месте. В примерах ниже будет использована папка /home/user/MyProject/venv.

Откройте окно командной строки и введите следующую команду. Подставьте путь к вашему виртуальному окружению.
```
python -m venv /home/user/MyProject/venv
```
Обновите менеджер пакетов для Python до последней версии.
```
/home/user/MyProject/venv/bin/pip install --upgrade pip
```

4. Установка Собираки #

Непосредственно сама Собирака занимает совсем немного места. Она написана на языке Python и полагается на перечисленные выше инструменты, чтобы выполнять всю грязную работу.

На этом этапе будет установлена сама Собирака, а также несколько зависимостей. Для установки используется pip — менеджер зависимостей для Python.

Откройте окно командной строки и введите следующую команду, чтобы установить или обновить Собираку в виртуальном окружении. Не забудьте подставить в команду правильный путь к вашему виртуальному окружению.
```
/home/user/MyProject/venv/bin/pip install sobiraka
```
Чтобы проверить установку, выполните следующую команду:
```
/home/user/MyProject/venv/bin/sobiraka --help
```
Появится краткий перечень доступных команд, начинающийся со слов usage: sobiraka. Если вы его видите — значит, всё прошло идеально!

5. Сборка документации #

Осталось сделать самое главное: начать писать документацию и собирать её с помощью Собираки.

Создайте новую папку для проекта документации, а в ней — подпапку src.
В папке проекта создайте файл sobiraka.yaml следующего содержания:
```
title: Пример документации
paths:
  root: src
```

В подпапке src создайте файл _index.md следующего содержания:

# Пример документации
Эта документация собирается Собиракой.

Откройте окно командной строки и перейдите в папку проекта. Например:
```
cd /home/user/MyProject
```
Чтобы собрать документацию в формате HTML, выполните следующую команду:
```
/home/user/MyProject/venv/bin/sobiraka web
```
Когда сборка завершится, готовые файлы появятся в поддиректории build/web. Чтобы посмотреть документацию, в любом браузере откройте файл build/web/index.html.
Чтобы собрать документацию в формате PDF, выполните следующую команду. Не забудьте подставить путь к вашему виртуальному окружению.
```
/home/user/MyProject/venv/bin/sobiraka pdf
```
Когда сборка завершится, готовый файл появится в поддиректории build/pdf.