Docs as code против или вместе с Confluence? Обзор нескольких способов публикации из репозитория в Confluence
Многие уже давно или активно используют или смотрят в сторону модели хранения и публикации документации как кода, это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду, например, хранить в репозитории, прогонять тесты, собирать и релизить в CI/CD. Этот подход позволяет поддерживать документацию актуальной к коду, версионировать и отслеживать изменения, используя привычные инструменты разработки.
Однако в то же время во многих компаниях годами существуют также и вики-системы, в которых к документации получают доступ другие команды и сотрудники, например, менеджеры проектов. Что если вам захотелось привести хранение и публикацию к единому виду, то есть наряду с HTML публиковать доки и в Confluence? В этой статье я дам обзор решений задачи публикации документов из репозитория в Confluence.
Одно решение я давно активно использую сама в команде разработки интерфейсов (связка RST-Sphinx+sphinxcontribbuilder), а остальные представлю в качестве альтернативы, сразу оговорюсь, что на практике я их не пробовала, только изучила конфигурацию.
Sphinx doc+sphinxcontribbuilder
Sphinx (не путать с одноименным поисковым индексом) — это генератор документации, написанный на Python и активно используемый сообществом, он вполне хорошо работает также и в других средах.
На его настройке мы останавливаться подробно не будем, оговорюсь лишь, что из коробки он умеет генерировать статический HTML, man, pdf, и еще ряд форматов, а для корректной сборки и публикации в репозитории должны быть файлы index.rst (разметка главной страницы), conf.py (файл конфигурации) и Makefile (файл, описывающий процесс генерации форматов, вот его вполне можно зашить в докер и запускать sphinx-build команду там).
Из коробки Sphinx умеет генерировать доки из легковесной разметки формата *.rst (RestructuredText), но мы добавили возможность писать и в Markdown (CommonMark flavor) для тех разработчиков, кому это удобнее (в этом нам помогло расширение m2r, которое конвертирует MD в RST).
У нас все окружение для Sphinx уже было настроено, а сборка документации зашита в отдельный стейдж в пайплайне в Jenkins, поэтому мы пошли дальше и использовали расширение sphinxcontrib.confluencebuilder, которое умеет собирать доки в нативном для Confluence формате, а затем публиковать их. Confluence в данном случае является одним из форматов вывода документации, наряду с HTML.
Чтобы это заработало, вам нужно подключить расширения в conf.py, ниже фрагмент конфигурации.
А затем конфигурировать расширение, у него есть набор настроек:
Названия страниц в Confluence будут соответствовать первому title страницы, например, если у вас в файле example.rst указан заголовок Example, подчеркнутый знаками равно, он станет названием страницы в Confluence.
Правило гигиены, довольно очевидное, но все же: создайте бота с авторизационными данными которого будете публиковать документы, их можно передавать в виде переменных окружения в docker compose, использовать в пайплайнах.
Конечно, есть и подводные камни. Во-первых, не весь синтаксис RST поддерживается для публикации в Confluence (╯°□°）╯︵ ┻━┻), это неудобно, если вы хотите из одного исходника собирать HTML и Confluence. Не поддерживаются директивы сontainer, hlist, почти все атрибуты директив, например, подсвечивание строк в код блоке, нумерация в оглавлении, align и width для listtable. Список того, что поддерживается, он довольно неплох.
Из приятного, поддерживаются includes, это позволяет переиспользовать фрагменты контента между разными документами, autodoc для сборки документации из кода, math для математических формул, отрисовка тикетов и фильтров из jira (для этого придется в конфигурации прописать еще и Jira сервер), нумерованные заголовки и многое другое, буквально 3 января закатили большое обновление.
Кстати, поддержка Jira появилась и в мультиконвертер Pandoc, начиная с версии 2.7.3 Pandoc поддержал соответствующую confluence wiki разметку.
Для тех макросов и элементов Confluence, которые не поддерживаются есть грязный хак. В RST есть директива … raw::, и у нее есть атрибут сonfluence, она принимает conf разметку, если вам очень нужен какой-то макрос — можно скопировать его в режиме редактирования страницы в Confluence (режим исходного кода доступен по иконке <>) и вставить его «сырой» код туда. Но я вас этому не учила.
Результат получается такой:
Почему нам понадобилось настраивать публикацию из локального репозитория на тестовую страницу, а не сразу на «прод»? Дело в том, что при публикации все страницы каждый раз публикуются заново и перетирают изменения, сделанные вручную или комменты в строке (inline). Поэтому, когда документ находится в работе, мы решили публиковать его в какую-то отдельную страницу, этакий dev mode, чтобы добавлять опубликованные версии в ревью и собирать комментарии.
На CI публикация реализована в виде отдельного стейджа в пайплайне в Jenkins, внутрь этого стейджа зашит запуск docker образа на удаленном реджистри, в котором реализован запуск sphinx-build с нужной конфигурацией. Лучше сразу сделать этот шаг пропускаемым.
Еще один нюанс: при каждой публикации сабсета страниц Sphinx обновляет все дерево, каждую страницу. То есть, даже если контент не менялся, создается изменение, если у вас настроены уведомления в канал, то он будет засоряться множеством уведомлений.
Еще несколько способов
Foliant с Confluence в качестве бэкэнда
Инструмент для генерации документации Foliant с Mkdocs и множеством препроцессоров под капотом и бэкэндом в виде Confluence. Подробнее можно почитать тут, но если кратко, то он использует pandoc для конвертации md в HTML, а затем публикует его в Confluence. Нужно только сконфигурировать бэкэнд и установить pandoc в окружение в качестве зависимости.
Выгодные отличия от первого решения: он умеет восстанавливать inline комментарии в тех же местах, что они были до перепубликации страницы, позволяет создавать страницы, задав их в конфиге, редактировать их названия, а также вставлять контент внутрь уже существующей страницы, для этого нужно вручную задать якорь foliant на странице в Confluence.
Работает только с исходником на Markdown.
Metro
Мультитул, который публикует самые разные форматы источников в Confluence, от Google Docs до Salesforce Quip, и в Markdown тоже умеет.
Gem md2conf
Ruby gem md2conf, он конвертирует Markdown в нативный для Confluence XHTML. Дальше можно написать Rake таску, которую в свою очередь можно вызывать через Gitlab CI/Jenkins по пушу в master, затем дергать Confluence API, чтобы опубликовать страницу. Чтобы не заносить к себе Ruby окружение, заверните зависимости для этого gem в контейнер.
Как отсылать запросы в Confluence API описано тут.
Работает только с исходником на Markdown.
Из найденного в Github
На самом деле таких скриптов или cli-инструментов в сообществе уже наделали некоторое количество, но экспериментировала я только с md2conf, все они делятся на две группы.
И те, что сразу реализовывают в себе и запросы к Confluence API, нужно только указать API ключ в конфиге:
P.S. Если вы поделитесь в комментариях другими найденными решениями задачи, я буду очень признательна.
А если хотите пообщаться на эти темы подробнее со мной, приходите на KnowledgeConf 2020 18 мая.
Как отформатировать встроенный код в Confluence?
14 ответов
чтобы вставить встроенный моноширинный шрифт в слияние, окружите текст двойными фигурными скобками.
Если вы используете Confluence 4.x или выше, вы также можете просто выбрать опцию «предварительно отформатированный» из меню стиля абзаца.
по умолчанию Confluence отображает однослойный текст с прозрачным фоном. Вы можете изменить глобальный CSS, чтобы добавить серый цвет. От руководство по слиянию:
пользовательский CSS для отображения серого фона в одноместных блоках:
если вы используете Confluence OnDemand (облако):
вы можете попросить своего администратора дьявольского слияния создать для вас макрос. Вот пример макроса для Confluence 3.x
затем пользователи могут использовать
вы также можете использовать или