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

Собираку можно запускать с помощью среды Docker на любой операционной системе: Windows, macOS или Linux. Этот способ запуска удобен тем, что позволяет не думать ни о каких зависимостях, кроме самого Docker.

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

На этом этапе необходимо установить среду запуска контейнеров Docker, если она ещё не установлена на вашем компьютере.

Проследуйте инструкциям с официального сайта Docker, чтобы установить один из вариантов среды:
- Установка Docker Desktop
  Содержит графический интерфейс для управления контейнерами.
- Установка Docker Engine
  Содержит только командный интерфейс, доступен только для Linux.
Чтобы проверить установку, откройте окно командной строки и выполните следующую команду:
```
docker run --rm alpine echo -e '\nIt works!'
```
Эта команда должна скачать небольшой Docker-образ из интернета, а затем вывести сообщение It works!. Если вы его видите, значит, Docker работает.

2. Загрузка образа Собираки #

Собирака поставляется в виде образов для среды Docker. В образы входит сама Собирака и её зависимости (в частности, язык программирования Python). На этом этапе необходимо скачать нужный образ, чтобы среда Docker могла использовать его в дальнейшем.

Скачайте нужный образ одной из следующих команд:
- Стандартный образ подходит для сборки HTML и сборки PDF через WeasyPrint. Это рекомендуемый образ для большинства пользователей.
```
docker pull documentat/sobiraka
```
- Образ с поддержкой LaTeX подходит для сборки HTML, сборки PDF через WeasyPrint и сборки PDF через LaTeX. Он включает в себя комплект инструментов LaTeX, который используется для оформления файлов PDF, поэтому этот образ занимает чуть больше места и скачивается дольше, чем стандартный образ. Если вы не знаете, что такое LaTeX, скорее всего, этот образ вам не нужен.
```
docker pull documentat/sobiraka-latex
```
  Обратите внимание, что далее в этой инструкции приводятся команды для стандартного образа. Если вы решили использовать образ с поддержкой LaTeX, не забывайте добавлять -latex к названию образа в командах.
Чтобы проверить установку, выполните следующую команду:
```
 docker run --rm documentat/sobiraka sobiraka --help
```
Появится краткий перечень доступных команд, начинающийся со слов usage: sobiraka.

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

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

Примечание для пользователей Windows

Примеры команд на этом этапе приведены для Linux и macOS. Если вы используете Windows, вам понадобится слегка отредактировать их перед запуском.

Различие состоит в том, как именно команда передаёт в Docker информацию о текущей директории (переменная $PWD в примерах):

для Командной строки замените $PWD на %cd%,
для PowerShell замените $PWD на ${PWD},
для Git Bash замените $PWD на /$(pwd).

Кроме того, если вы используете Windows, удаляйте во всех командах параметр -it.

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

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

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

Откройте окно командной строки и перейдите в папку проекта. Например:
```
cd /home/user/myclient/docs
```
Чтобы собрать документацию в формате HTML, выполните следующую команду:
```
docker run --rm -it -v $PWD:/W documentat/sobiraka sobiraka web
```
Когда сборка завершится, готовые файлы появятся в поддиректории build/web. Чтобы посмотреть документацию, в любом браузере откройте файл build/web/index.html.
Чтобы собрать документацию в формате PDF, выполните следующую команду:
```
docker run --rm -it -v $PWD:/W documentat/sobiraka sobiraka pdf
```
Когда сборка завершится, готовый файл появится в поддиректории build/pdf.