Автоматическая генерация отчётов по ГОСТ в DOCX из скриптов Engee

На основе скриптов Engee можно создавать документы Word с титульным листом, в которые автоматически попадают все выходные данные документа, а также текст, код и результаты выполнения скриптов.

Описание примера

В этом проекте мы демонстрируем, как организовать генерация отчётов по гост на основе интерактивных скриптов, выполненных в Engee.

Когда инженерный или научный процесс требует регулярно выпускать однотипный документ с фиксированной структурой и соблюдением требований к оформлению, в качестве источника данных может использоваться ваш скрипт (.ngscript), содержащий текст, результаты вычислений, формулы и другие элементы модели, а результат может быть оформлен согласно указанному шаблону (в формате .docx).

Генератор осуществляет прямую трансляцию из одного формата в другой:

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

После загрузки параметров и создания исходного шаблона, наш алгоритм наполняет шаблон строками из указанного файла .ngscript.

Ограничения генератора

На данный момент не поддерживаются матрицы в формулах (ограничения транслятора), также не поддерживается графика в SVG формате (ограничения DOCX). Документы лучше открываются в MS Word, другие редакторы более требовательны к синтаксису формул.

Возможности генератора

Генератор принимает на вход:

Один .ngscript или .ipynb файл
Папку с несколькими .ngscript/.ipynb файлами (автоматически объединяются в один документ)

Внутри ноутбука обрабатываются:

Markdown-ячейки — заголовки, списки, таблицы, изображения, формулы
Кодовые ячейки — исходный код (опционально), графический вывод, DataFrame-таблицы, текстовый вывод
Встроенный конфиг в формате TOML в любой ячейке

Вот некоторые полезные возможности генератора документации:

Титульный лист с настраиваемыми полями: учебное заведение, тип работы, название, автор, руководитель, город, год. Подписи «Выполнил»/«Принял» также настраиваются.
Автонумерация заголовков трёх уровней (1, 1.1, 1.1.1).
Изображения с автоматическими подписями «Рисунок N — Название» (сквозная нумерация).
Таблицы с автоматическими подписями «Таблица N — Название» (сквозная нумерация). Таблицы могут быть как из markdown-разметки, так и из вывода DataFrame.
Формулы LaTeX с автоматической нумерацией в пределах главы, поддержка inline и display-режима, дробей, степеней, индексов, корней, систем уравнений (cases).
Управление видимостью кода: можно скрыть код, оставив только результат (#DOCX_GENERATION_ONLY_OUTPUT), или полностью исключить ячейку из отчёта (#DOCX_SKIP).
Привязка подписей к таблицам и изображениям — они не отрываются при переносе страниц.
Колонтитулы: верхний с названием организации (первая страница) и информацией (последующие), нижний с городом/годом (первая) и номерами страниц (последующие).

Внутри текстовых ячеек обрабатываются:

Текст:
- Обычный текст с автоопределением кодировки
- Жирный (**текст**)
- Курсив (*текст*)
- Инлайн-код (`код`)
Заголовки (три уровня с автонумерацией):
- # Заголовок → «1 Заголовок»
- ## Подзаголовок → «1.1 Подзаголовок»
- ### Подподзаголовок → «1.1.1 Подподзаголовок»
Списки (маркированные):
- * элемент или - элемент
- Изображения:
- ![alt-текст](attachment:имя_файла "Подпись") — встроенные изображения
- Форматы: PNG, JPEG (через base64)
- Автоподпись «Рисунок N — Подпись»
Таблицы:
- Строгий формат:
  
  text
```
#|
||Заголовок1 | Заголовок2||
||Ячейка1 | Ячейка2||
|#
```
- С подписью (предваряется DOCX_TABLE_NAME: Название) или без
- Автоподпись «Таблица N» или «Таблица N — Название»
Формулы:
- Инлайн: $L = \alpha \cdot P^{\beta}$
- Выключные с автонумерацией: $$L = \alpha \cdot P^{\beta}$$
Поддерживаемые элементы LaTeX:
- Греческие буквы: \alpha, \beta, \gamma, ..., \Omega
- Операторы: \cdot, \times, \div, \pm, \mp
- Отношения: \leq, \geq, \neq, \approx, \equiv, \propto, \sim
- Стрелки: \rightarrow, \leftarrow, \Rightarrow, \Leftarrow, \leftrightarrow
- Спецсимволы: \infty, \partial, \nabla, \forall, \exists, \in, \notin
- Множества: \subset, \supset, \cup, \cap
- Числовые множества: \mathbbR, \mathbbN, \mathbbZ, \mathbbC
- Тригонометрия: \sin, \cos, \tan, \cot, \arcsin, ...
- Логарифмы: \log, \ln, \lg, \lim, \max, \min
- Дроби: \frac{числитель}{знаменатель}, \dfrac
- Степени: x^{n}, x^n
- Индексы: x_{n}, x_n
- Корни: \sqrt{выражение}
- Точки над символами: \dot{x}, \ddot{x}
- Системы уравнений: \begin{cases}...\end{cases}
- Смена шрифта: \mathbb{...}, \mathbf{...}, \mathcal{...}

При помещении в документацию кодовых ячеек поддерживаются:

Исходный код:
- Отображается моноширинным шрифтом на сером фоне (стиль Code)
- Можно скрыть через #DOCX_GENERATION_ONLY_OUTPUT или no_code=true
Результаты выполнения:
- Изображения (MIME: image/png, image/jpeg):
  - Автоподпись при наличии #DOCX_GENERATION_PLOT_TITLE Название
  - Формат подписи: «Рисунок N — Название»
- HTML-таблицы (MIME: text/html):
  - Вывод DataFrame через show(stdout, MIME("text/html"), df)
  - Автоподпись при наличии #DOCX_TABLE_NAME: Название
  - Парсинг <thead>, <th>, <tr>, <td>
- Текстовый вывод (MIME: text/plain, text):
  - Моноширинный шрифт (стиль CodeOutput)
Управляющие аннотации (строки с # в коде):
- #DOCX_SKIP — полностью исключить ячейку из отчёта
- #DOCX_GENERATION_ONLY_OUTPUT — скрыть код, показать вывод
- #DOCX_GENERATION_PLOT_TITLE Название — подпись к графику
- #DOCX_TABLE_NAME: Название — название для DataFrame-таблицы

Поддерживается помещение выходной информации как во внешний файл, так и в конфигурационную ячейку (в markdown или кодовой ячейке):

Секции: [template], [title_page], [extra_labels], [content], [custom_fields]
В кодовых ячейках строки предваряются #
Автоматически исключается из отчёта
Приоритет: аргументы функции > встроенный конфиг > внешний config.toml

Шаблон документа

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

Вы можете скачать, отредактировать этот файл и загрузить его обратно в файловый браузер Engee. Генератор найдёт в нём поля с разметкой типа {{WORK_TITLE}}, куда подставит информацию на место всех полей, по возможности соблюдая стили документа.

Источники данных

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

Что касается титульного листа и колонтитулов, генератор первым делом загружает выходную информацию документа из файла config.toml. Это позволяет нам не перегружать команду запуска генератора отчёта расширенным количеством аргументов, хотя их тоже можно указать в качестве дополнительных параметров.

Три способа задания данных для форматирования документа:

Задать в качестве аргументов команды generate_report
Хранить в сопровождающем файле config.toml
Поместить файл config.toml в одну из ячеек (текстовую, в виде врезки, или кодовую, в виде комментария)

Как запустить скрипт генератора отчётов

Чтобы сгенерировать тестовые файлы в текущей папке, запустите ячейку:

include("$(@__DIR__)/scripts/generate_report.jl")
generate_report()

(-) Папка или файл не найдены: ./content
(+) Создаю тестовый файл DEMO_REPORT_EXAMPLE.ngscript ...
   Создан файл: DEMO_REPORT_EXAMPLE.ngscript
(-) Файл конфига не найден. Создаю config.toml с настройками по умолчанию.
   Создан файл: config.toml
   (!) Вы можете отредактировать config.toml и запустить скрипт снова.
(-) Шаблон не найден. Создаю новый: template.docx
   (!) Вы можете открыть этот файл в Word и настроить стили.
(+) Загружен внешний конфиг из config.toml
(+) Отчёт создан: report.docx

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

Вы можете запустить генератор с вашим собственным файлом notebook_test.ngscript:

generate_report("notebook_test.ngscript", output_path="Отчет.docx")

Или можете сгенерировать целый учебник, указав в качестве аргумента не отчет, а папку с файлами:

generate_report("./content", output_path="Учебник.docx")

Для более успешной генерации отчета:

При размещении в финальном документе графики и изображения не масштабируются. Лучше сразу выставить им желаемый dpi или размер в пикселях, например при помощи команды gr(size=(600,400), fmt=:png). Интерактивные графики не поддерживаются в Word, поэтому лучше выводить их в формате png.

Заключение

Этот небольшой проект показывает, как вы можете создавать генераторы документации из скриптов Engee. Доработав его вы можете автоматизировать документооборот, включающий генерацию снимков моделей и импорт данных из других сопутствующих файлов.