Engee documentation
Notebook

Automatic generation of GOST reports in DOCX from Engee scripts

Based on Engee scripts, you can create Word documents with a title page, which automatically contain all the output data of the document, as well as text, code, and script execution results.

Description of the example

In this project, we demonstrate how to organize the generation of GOST reports based on interactive scripts executed in Engee.

When an engineering or scientific process requires the regular release of a document of the same type with a fixed structure and compliance with design requirements, your script can be used as a data source (.ngscript), containing text, calculation results, formulas, and other model elements, and the result can be formatted according to the specified template (in the format .docx).

The generator performs a live broadcast from one format to another:

  • the entire text, headings, code, images and graphs get into the document from the script.,
  • formulas are partially translated - the translator supports special signs, ratio operators, degrees, subscripts and fractions, some types of matrices and systems of equations.

After loading the parameters and creating the initial template, our algorithm fills the template with lines from the specified file. .ngscript.

Currently, matrices in formulas (limitations of the formula translator), multilevel lists, and graphics in SVG format (limitations of DOCX) are not supported. Documents open better in MS Word, other editors are more demanding on the syntax of formulas.

Generator Features

The generator accepts input:

  • One .ngscript or .ipynb file

  • A folder with several .ngscript/.ipynb files (automatically combined into one document)

Inside the laptop, the following are processed:

  1. Markdown-Cells — headings, lists, tables, images, formulas
  2. Code cells — source code (optional), graphical output, DataFrame tables, text output
  3. Built-in config in TOML format in any cell

Here are some useful features of the documentation generator:

  • Title page with customizable fields: educational institution, type of work, title, author, supervisor, city, year. The signatures "Completed"/"Accepted" are also configurable.

  • Auto-numbering of headings of three levels (1, 1.1, 1.1.1).

  • Images with automatic captions "Figure N — Title" (end-to-end numbering).

  • Tables with automatic labels "Table N — Name" (end-to-end numbering). Tables can be either from markdown markup or from the output of a DataFrame.

  • **LaTeX formulas with automatic numbering within the chapter, support for inline and display mode, fractions, degrees, indices, roots, systems of equations (cases).

  • Code visibility control: you can hide the code, leaving only the result (#CODE_SKIP), or completely exclude the cell from the report (#SKIP).

  • Linking captions to tables and images — they don't come off when you move pages.

  • Headers and footers: the upper one with the name of the organization (first page) and information (subsequent), the lower one with the city/year (first) and page numbers (subsequent).

Inside the text cells are processed:

  • Text:

  • Plain text with automatic encoding detection

    • Bold (**текст**)

  • Italics (*текст*)

    • Инлайн-код (`код`)

  • Headers (three levels with auto-numbering):

    • # Заголовок → "1 Header"
    • ## Подзаголовок → "1.1 Subtitle"
    • ### Подподзаголовок → «1.1.1 The subtitle"

  • Lists (bulleted):

    • * элемент or - элемент
    • Images:
    • ![alt-текст](attachment:имя_файла "Подпись") — embedded images

  • Formats: PNG, JPEG (via base64)

  • Auto—signature "Figure N - Signature"

  • Tables:

  • Strict format:

    #|
||Заголовок1 | Заголовок2||
||Ячейка1 | Ячейка2||
|#

    • С подписью (предваряется #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_CODE_SKIP или no_code=true

  • Результаты выполнения:

    • Изображения (MIME: image/png, image/jpeg):

      • Автоподпись при наличии #DOCX_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)

  • Управляющие аннотации (строки с # в коде):

    • #SKIP — полностью исключить ячейку из отчёта
    • #CODE_SKIP — скрыть код, показать вывод
    • #PLOT_TITLE Название — подпись к графику
    • #TABLE_NAME Название — название для DataFrame-таблицы

It supports placing output information both in an external file and in a configuration cell (in markdown or a code cell):

  • Sections: [template], [title_page], [extra_labels], [content], [custom_fields]

  • In the code cells, the lines are preceded by #

  • Automatically excluded from the report

  • Priority: function arguments > built-in config > external config.toml

Document Template

First of all, the generator loads a document template, which it will fill with data. It can be specified in the command argument, the standard template name.: template.docx. If there is no template file with the desired name in the specified directory, the generator creates such a file.

You can download and edit this file and upload it back to the Engee file browser. The generator will find fields with markup like {{WORK_TITLE}}, where it will replace the information in the place of all fields, observing the styles of the document as much as possible.

Data sources

The report body is generated from a file .ngscript, the location of which is passed to the generator via arguments.

As for the title page and footers, the generator first loads the output information of the document from the file. config.toml. This allows us not to overload the report generator startup command with an extended number of arguments, although they can also be specified as additional parameters.

Three ways to specify data for formatting a document:

  1. Set the following commands as arguments report_compile
  2. Store in the accompanying file config.toml
  3. Place the config.toml file in one of the cells (text, as an inset, or code, as a comment)

How to run the report generator script

To generate test files in the current folder, run the cell:

In [ ]: 
include("$(@__DIR__)/report_compiler.jl")
report_compile()

(+) The file is automatically selected: report_compiler_article.ngscript
(+) The external config is loaded from config.toml
(+) The report has been created: report.docx

An example document is created without the results of the execution. In your script, most likely, the script will already contain the results - text, graphs, and tables.

You can run the generator with your own file. notebook_test.ngscript:

report_compile("notebook_test.ngscript", output_path="Report.docx")

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

report_compile("./content", output_path="Учебник.docx ")
```</span>

For more successful report generation:

When placed in the final document, the graphics and images are not scaled. It is better to set them the desired dpi or pixel size immediately, for example, using the command gr(size=(600,400), fmt=:png). Interactive graphs are not supported in Word, so it is better to output them in png format.

~Conclusion

This small project shows how you can create documentation generators from Engee scripts. After completing it, you can automate workflow, including the generation of snapshots of models and the import of data from other related files.

P.S.: And the "tilde" icon (~) before the word "Conclusion" created an unnumbered title for us.