Автоматическая генерация отчётов по ГОСТ в 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. Доработав его вы можете автоматизировать документооборот, включающий генерацию снимков моделей и импорт данных из других сопутствующих файлов.

Трансляция скрипта Engee в отчёт по ГОСТ

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

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

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

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

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

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

Заключение

Тип

Краткое описание

Связанные материалы

Теги

Категории

Языки

Форматы

Уровень

Статус

Опубликовано

Обновлено

Источник