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

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

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

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

• Используйте любой git-терминал, который позволит сделать git pull с вашего репозитория. Не забудьте сделать сперва git fetch.

• Ознакомьтесь с концепцией фреймворка docToolchain и установите его. Фреймворк позволяет конвертировать asciidoc в другие различные форматы. Установка описана на сайте.
  

  • Если вы решили устанавливать концепты архитектуры Arc42, то прочитайте информацию под спойлером.

• Установите два дополнительных плагина - reveal.js и asciidoctor-reveal.js.

• Установите Pandoc - еще один универсальный текстовый конвертер. DocToolchain использует Pandoc в своей цепочке конвертации. Установка Pandoc подробно описана на сайте.

• Теперь установите Gradle - это наша автоматическая сборка. Как установить Gradle, можно почитать на сайте.

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

• Еще вам понадобится Groovy. Про установку Groovy можно почитать на сайте документацию от разработчиков.

• Скачайте потоковый текстовый редактор sed.Нам он понадобится для поиска и замены текстовых блоков в нашем docx.

• И последняя утилита - UnZip-архиватор.

Структура docToolchain

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

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

1. Верхнеуровневое наименование каталога, куда установлен наш фреймворк docToolchain.

2. В этом каталоге хранятся файлы запуска самого docToolchain. Если фреймворк прописан в системном окружении (systemPATH%), то запуск будет доступен из любого каталога.

3. Основной каталог нашего проекта. Именно данный каталог мы инициализируем командой:

   ./gradlew -b init.gradle initExisting -PnewDocDir=<your directory>

4. Каталог со скриптами конвертации.

5. Важный для нас файл на текущем этапе. В данном файле прописываем сценарий трансформации из adoc в docbook, а потом в docx.

   Hidden text

   По непонятным мне причинам конфигурация отдельного файла, созданного исключительно под проект, не работает. Так что конфигурируем глобальный файл.

6. Глобальный файл с настройками Groovy.

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

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

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

1. Каталог нашего проекта. В этом каталоге содержатся мастер-файлы, которые будут преобразованы.

2. Каталог, который содержит сборочные папки для разных форматов. Именно сюда перемещаются собранные файлы, т.е., если мы собираем docx, то запуск сборочного скрипта создаст папку docx и поместит сюда созданный ${filename}.docx.

3. Искомый файл в формате docx. Имя файла берется от имени файла, который мы преобразовываем.

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

5. Используемый в качестве шаблона docx-файл.

6. В концепции фреймворка docToolchain данный каталог должен использоваться для контента, указанного в мастер-файлах, например, в виде инклюдов asciidoctor-файлов.На самом деле, от такой концепции можно отойти и ориентироваться на структуру каталогов, которую мы задаём для нашего git-дерева. Подробнее об этом будет изложено ниже.

7. Каталог, взятый как раз из git-дерева, в котором содержатся adoc-файлы с контентом.

8. Конфигурационный файл Groovy.

9. Мастер-файл, содержащий инклюды, который будет трансформироваться в docx.

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

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

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

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

1. Проектная ветка, содержащая типы документации.

2. Тип руководства, которое мы будем трансформировать в docx.

3. Начиная с данного каталога, содержимое каталога необходимо будет скопировать в каталог нашего проекта.
   

4. Каталог с изображениями. Каталог необходим для корректной трансформации.

5. Каталог, содержащий контент нашего руководства. Весь контент задекларирован в виде инклюдов в мастер-файле.

6. Сам мастер-файл. Содержит инклюды, логику визуальной трансформации и т.п.

7. Объекты 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-->
                    ]

где:

1. Ключ -s, через который мы принудительно задаём тип для ${input}.docx.

2. После ключа --reference-doc= мы прописываем путь к нашему docx-шаблону.

3. Ключ --toc принудительно задаёт генерацию оглавления для docx.

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

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

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

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

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

где:

1. Устанавливает ${inputPath} для конвертации из docbook в docx. Надо задать именно так, как на примере.

2. Наш docx-шаблон.

3. Мастер-файл, который мы будем конвертировать.

4. Типы файлов, в которые мы будем конвертировать наш asciidoc-файл.

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

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

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

doctoolchain docs convertToDocx

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

Замена Table of Contents

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

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

1. Поместите полученный docx-файл в любую временную директорию.

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

#!/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

где:

1. Скрипт распаковывает указанный docx-файл.

2. Здесь мы указываем что надо заменить ${Table of Contents}, на что мы будем менять (${Оглавление} как пример).

3. Где мы будем менять. Как видно, sed меняет данные в уже распакованном docx.

4. Происходит обратная упаковка с указанием имени нового файла. Рекомендую всегда создавать новый файл.

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

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

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

bash find.sh

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

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