0055 — Antora для Sphinx

На работе грядёт новый проект, и пока требования не ясны, решил посмотреть, какие инструменты есть для управления несколькими версиями документации сразу. Сразу скажу, что ищу варианты только Docs-as-Code, поэтому всякие расширения Confluence, Documenterra и прочие в принципе не рассматриваю.

Посмотрел Antora — проект написан на JavaScript, для работы требует раковую опухоль NodeJS, исходники документации могут быть только в формате AsciiDoc.

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

1. Создаётся отдельный проект, в котором самый главный файл — antora-plyabook.yml.

   В этом файле описывается несколько параметров, влияющих на сборку:

   • site — параметры собираемого сайта.

   • content — источники содержимого. Здесь происходит самое интересное:

     • content.sources.url — ссылка на репозиторий с документацией в формате AsciiDoc;
     • content.sources.branches — список ссылок, на основе которых формируются версии документации: названия веток или тегов, можно использовать указатель HEAD.

   • ui.bundle.url — ссылка на ZIP-архив с темой;

   • ui.bundle.snapshot — требование всегда собирать проект с самой новой версией темы.

2. Создаётся отдельный проект для темы. Там только шаблоны. В качестве отправной точки рекомендуется использовать репозиторий Antora Default UI.

3. Создаются проекты документации в формате AsciiDoc, к которым предъявляются дополнительные требования.

Сначала мне такая структура показалась довольно сложной. Однако, логика авторов Antora понятна. Они пытались решить следующие задачи:

• Отделение документации от оформления.

• Использование одного UI для всех источников, описанных в antora-playbook.yml.

• Поддержка многоверсионности, причём для каждого компонента в рамках одного проекта можно вести свою историю веток.

  Мне кажется, это самая важная особенность Antora. Ничего подобного для Sphinx я не видел.

Поискал похожий инструмент для Sphinx, и ничего не нашёл. Неужели свободная ниша для OpenSource-решения, которое изменит всё?