alexd1971/dartdoc_autobuild repository overview

⁠Сервис автоматической генерации документации для пакетов на языке DART

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

⁠Принцип работы сервиса

Сервис представляет собой github webhook и обслуживает события push и pull_request в репозиториях, настроенных на этот webhook

При получении запроса от github об изменениях в репозитории сервис обновляет соответствующий локальный репозиторий и генерирует документацию. После этого пересобирается индекс

Для получения доступа к документации необходимо настроить внешний web-сервер для статических страниц.

⁠Установка и запуск сервиса

Хотя существует возможность непосредственного запуска сервиса, но лучше всего сервис установить и запустить в docker-контейнере, так как сам сервис не подразумевает какого-либо конфигурирования. В частности без правок кода невозможно изменить директории для репозиториев и документации, а также порт, на котором слушает сервис. Все эти настройки возможно сделать при запуске в docker-контейнере. Поэтому будем рассматривать только запуск сервиса в docker-контейнере.

⁠Запуск с помощью команды

docker run --name dart_docs -e DARTDOC_AUTOBUILD_INDEX_TITLE="Title" -e DARTDOC_AUTOBUILD_INDEX_HEADER="Documentation Index" -v repos:/app/repos -v /var/www/docs:/app/docs -p <port>:7777 alexd1971/dartdoc_autobuild

/var/www/docs -- путь к директории, где будет формироваться документация по пакетам и индекс; для получения доступа к документации эта директория должна обслуживаться web-сервером.

port -- порт, на котором будет слушать webhook; этот порт может быть произвольным, главное, чтобы к нему было настроено проксирование извне. На этот порт будут отправляться запросы с github

По умолчанию title индексной страницы устанавливается в Index page. Для изменения значения по умолчанию нужно установить значение переменной окружения DARTDOC_AUTOBUILD_INDEX_TITLE

По умолчанию заголовок индексной страницы устанавливается в Documentation index. Для изменения значения по умолчанию нужно установить значение переменной окружения DARTDOC_AUTOBUILD_INDEX_HEADER

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

⁠Запуск с помощью docker-compose

Для запуска с помощью docker-compose необходимо создать следующий файл docker-compose.yml:

version: "3"

services:
  docs:
    image: alexd1971/dartdoc_autobuild
    container_name: dartdoc
    environment:
      DARTDOC_AUTOBUILD_INDEX_TITLE: "Index Title"
      DARTDOC_AUTOBUILD_INDEX_HEADER: "Index Header"
      DARTDOC_AUTOBUILD_GITHUB_TOKEN: <Github token should be here>
    volumes:
      - repos:/app/repos
      - /var/www/docs:/app/docs
    ports:
      - 7777:7777
volumes:
  repos:
    driver: local

⁠Настройка

Для корректной работы сервиса на сервере, где запущен сервис необходимо настроить следующее:

1. Прокси пробрасывающий запросы на некий URL, например, https://webhook.example.com на http://localhost:<port>
2. Web-сервер, отдающий статические страницы из каталога /path/to/documentation/dir

⁠Подключение репозиториев к сервису

Для подлкючения репозитория к сервису необходимо зайти в настройки (Settings) репозитория на github. Далее переходим а раздел Webhooks и там создать новый webhook.

⁠Настройка webhook

• Payload URL настроенный URL для входящих запросов с github (https://webhook.example.com)
• Content-Type -- application/json
• Выбираем Let me select individual events и устанавливаем Pushes (выбрано по умполчанию) и Pull requests
• Нажимаем кнопку Add webhook

Дальше при каждом обновлении репозитория через push или merge pull request будет обновляться документация по пакету.