Статья про то, как можно собрать docx-файл из git(adoc)-дерева.

Стоит отметить, что тестировалось на Windows, но не факт, что в 100% случаях всё будет работать как надо.

Необходимые утилиты

Ваши предварительные действия:

Используйте любой git-терминал, который позволит сделать git pull с вашего репозитория. Не забудьте сделать сперва git fetch.
Ознакомьтесь с концепцией фреймворка docToolchain и установите его. Фреймворк позволяет конвертировать asciidoc в другие различные форматы. Установка описана на сайте.
- Если вы решили устанавливать концепты архитектуры Arc42, то прочитайте информацию под спойлером.

Hidden text

Нет необходимости использовать шаблоны Arc42, лучше инициализируйте свой пустой каталог.

Установите два дополнительных плагина - reveal.js и asciidoctor-reveal.js.
Установите Pandoc - еще один универсальный текстовый конвертер. DocToolchain использует Pandoc в своей цепочке конвертации. Установка Pandoc подробно описана на сайте.
Теперь установите Gradle - это наша автоматическая сборка. Как установить Gradle, можно почитать на сайте.

Не устанавливайте Gradle версии 8.0 и выше! Что-то с ним не то.

Еще вам понадобится Groovy. Про установку Groovy можно почитать на сайте документацию от разработчиков.
Скачайте потоковый текстовый редактор sed.Нам он понадобится для поиска и замены текстовых блоков в нашем docx.
И последняя утилита - UnZip-архиватор.

Структура docToolchain

После развёртывания фреймворка и инициализации каталога проекта структура папок проекта будет выглядеть примерно так (тут убраны ненужные каталоги и файлы!):

Структура для нашего docToolchain-проекта

Что в этой структуре каталогов нам важно:

Верхнеуровневое наименование каталога, куда установлен наш фреймворк docToolchain.
В этом каталоге хранятся файлы запуска самого docToolchain. Если фреймворк прописан в системном окружении (systemPATH%), то запуск будет доступен из любого каталога.
Основной каталог нашего проекта. Именно данный каталог мы инициализируем командой:
```
./gradlew -b init.gradle initExisting -PnewDocDir=<your directory>
```
Каталог со скриптами конвертации.
Важный для нас файл на текущем этапе. В данном файле прописываем сценарий трансформации из adoc в docbook, а потом в docx.
Hidden text
По непонятным мне причинам конфигурация отдельного файла, созданного исключительно под проект, не работает. Так что конфигурируем глобальный файл.
Глобальный файл с настройками Groovy.

Структура проекта

Структура каталога нашего проекта:

Наша структура каталогов с документацией

Давайте рассмотрим структуру:

Каталог нашего проекта. В этом каталоге содержатся мастер-файлы, которые будут преобразованы.
Каталог, который содержит сборочные папки для разных форматов. Именно сюда перемещаются собранные файлы, т.е., если мы собираем docx, то запуск сборочного скрипта создаст папку docx и поместит сюда созданный ${filename}.docx.
Искомый файл в формате docx. Имя файла берется от имени файла, который мы преобразовываем.
Хранилище референсных docx-файлов. В этот каталог мы помещаем те docx-файлы, которые мы будем использовать в качестве docx-шаблонов для трансформации.
Используемый в качестве шаблона docx-файл.
В концепции фреймворка docToolchain данный каталог должен использоваться для контента, указанного в мастер-файлах, например, в виде инклюдов asciidoctor-файлов.На самом деле, от такой концепции можно отойти и ориентироваться на структуру каталогов, которую мы задаём для нашего git-дерева. Подробнее об этом будет изложено ниже.
Каталог, взятый как раз из git-дерева, в котором содержатся adoc-файлы с контентом.
Конфигурационный файл Groovy.
Мастер-файл, содержащий инклюды, который будет трансформироваться в docx.

Подготовка файлов для трансформации

Давайте посмотрим на структуру нашего git-дерева, который мы склонировали себе локально:

Типичная git-структура для проектов на базе adoc

Стоит отметить, что такая структура более свойственна тем проектам документации, которые в полной мере соответствуют парадигме docs-as-code и используют asciidoc в качестве языка разметки.

Давайте кратко рассмотрим основные, как мне кажется, каталоги дерева.

Проектная ветка, содержащая типы документации.
Тип руководства, которое мы будем трансформировать в docx.
Начиная с данного каталога, содержимое каталога необходимо будет скопировать в каталог нашего проекта.
Каталог с изображениями. Каталог необходим для корректной трансформации.
Каталог, содержащий контент нашего руководства. Весь контент задекларирован в виде инклюдов в мастер-файле.
Сам мастер-файл. Содержит инклюды, логику визуальной трансформации и т.п.
Объекты 4, 5 и 6 мы копируем в корень нашего проекта.

Настройка pandoc.gradle

В данном скрипте мы переопределяем некоторые атрибуты, заданные по умолчанию.

Рекомендую сделать резервную копию данного файла.

        if(referenceDocFile?.trim()) {
            args = ["-r","docbook",
                    "-s", <!--1-->
                    "-t","docx",
                    "-o","../docx/$targetFile",
                    "--reference-doc=../docx/gost.docx" <!--2-->
                    ,sourceFile,
                    "--toc" <!--3-->
                    ]

где:

Ключ -s, через который мы принудительно задаём тип для ${input}.docx.
После ключа --reference-doc= мы прописываем путь к нашему docx-шаблону.
Ключ --toc принудительно задаёт генерацию оглавления для docx.

Настройка config.groovy

Данный файл генерится автоматически в папке проекта после выполнения процедуры инициализации.

inputPath = '.'; <!--1-->

referenceDocFile = "gost.docx" <!--2-->

inputFiles = [
       [file: 'API.adoc' <!--3-->
       ,formats: ['html','pdf','docbook','docx' <!--4-->
       ]],
]

где:

Устанавливает ${inputPath} для конвертации из docbook в docx. Надо задать именно так, как на примере.
Наш docx-шаблон.
Мастер-файл, который мы будем конвертировать.
Типы файлов, в которые мы будем конвертировать наш asciidoc-файл.

Мы можем исключить форматы html и pdf, но docbook и docx должны быть указаны явно.

Запуск скрипта

Для запуска скрипта, из терминала выполните команду:

doctoolchain docs convertToDocx

В результате выполнения команды Gradle выполнится task, указанный нами в файле pandoc.gradle.

Замена Table of Contents

После преобразования из одного формата в другой, наш полученный docx-файл содержит наименование для оглавления на английском языке.

Для смены языка в автоматическом режиме:

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

#!/bin/sh

    unzip API.docx <!--1-->
    -d tmp #unzip
    sed -i '' -e "s/Table of Contents/Оглавление/g" <!--2-->
    tmp/word/document.xml <!--3-->
    #find/replace
    cd tmp && zip -r ../API1.docx <!--4-->
     * && cd .. #zip
    rm -rf tmp

где:

Скрипт распаковывает указанный docx-файл.
Здесь мы указываем что надо заменить ${Table of Contents}, на что мы будем менять (${Оглавление} как пример).
Где мы будем менять. Как видно, sed меняет данные в уже распакованном docx.
Происходит обратная упаковка с указанием имени нового файла. Рекомендую всегда создавать новый файл.

Откройте скопированный docx-файл. Ваш Word-редактор выведет предупреждающее окно с разрешением сформировать TOC.Сделайте это и сохраните файл.

Это шаг очень важен!

Выполните скрипт из терминала.

bash find.sh

Hidden text

Для запуска скрипта через bash под Windows вы можете использовать различные методы, например, BusyBox 64 или MSYS2.

Таким образом, мы получили docx-файл из заранее заданного шаблона, используя современные системы хранения документации.

Также, мы немного затронули структуру docx-файла и смогли простыми скриптами по сути автоматизировать рутинные действия.

Собираем DOCX из ADOC