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

Прежде чем продолжить, убедитесь, что вы можете выполнять команды в командной строке. В зависимости от ваших настроек и предпочтений для этого можно использовать Командную строку, PowerShell или Git Bash.

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

Все команды следует выполнять в одном и том же варианте командной строки. Например, если вы решили использовать Git Bash, то используйте именно его на всех этапах.

Если вы используете Git Bash, во всех путях используйте прямой слеш, а не обратный: /, а не \.

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

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

Перейдите по ссылке: https://www.python.org/downloads/.
Нажмите большую жёлтую кнопку, чтобы скачать установщик Python.
Запустите установщик.

На первом экране установщика рекомендуется выбрать опцию Add Python 3.13 to PATH, чтобы командная строка Windows понимала короткую команду python вместо громоздкого пути до файла python.exe.
Пройдите все шаги установщика до конца.
Чтобы проверить установку, откройте окно командной строки и введите следующую команду.

Если при установке вы не выбрали опцию Add Python 3.13 to PATH (см. выше), то замените здесь python на полный путь, например, C:\Python\python.exe.
```
python --version
```
Появится текст наподобие Python 3.13. Если версия не ниже 3.11, значит, всё отлично.

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

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

Скачайте установщик Pandoc: pandoc-3.7-windows-x86_64.msi.
Запустите установщик и пройдите все его шаги до конца.
Чтобы проверить установку, откройте окно командной строки и введите следующую команду:
```
pandoc --version
```
Появится текст, начинающийся со строчки pandoc 3.7.

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

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

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

Откройте окно командной строки и введите следующую команду. Подставьте путь к вашему виртуальному окружению, а также при необходимости замените python на полный путь до файла python.exe.
```
python -m venv C:\MyProject\venv
```
Обновите менеджер пакетов для Python до последней версии.
```
C:\MyProject\venv\Scripts\pip install --upgrade pip
```

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

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

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

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

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

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

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

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

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

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