На работе грядёт новый проект, и пока требования не ясны, решил посмотреть, какие инструменты есть для управления несколькими версиями документации сразу. Сразу скажу, что ищу варианты только 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-решения, которое изменит всё?