Автоматизация оформления документации

в 10:44, , рубрики: csv, ERP-системы, jinja2, latex, python, XML, визуализация данных, документация, документирование

Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.

Описание должно было в себя включать:

  • Планы разработки ПО
  • Требования к ПО
  • Описание реализации требований к ПО
  • Таблицы трассируемости(соответствия) требований к ПО и реализации
  • Описание тестов на ПО (Примеры и процедуры верификации ПО)
  • Таблицы трассируемости(соответствия) требований к ПО и тестов
  • Отчет об обнаруженных проблемах
  • Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)

Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.

Автоматизация оформления документации - 1

Далее в статье я расскажу как я решил эту проблему.

Архитектура генератора документации

Поэтому было решено использовать автоматизированные средства, которые создают все документы, используя данные из первичных документов — таблиц в формате CSV, XML документов. При любых изменениях в проекте — можно запустить заново генерацию комплекта документации.

Таблицы в формате CSV удобно редактировать в табличном процессоре. Данные о проекте (текущую версию, наименование, совместимое оборудование) хранил в формате XML.

Описание реализации требований уже содержится в doxygen комментариях к исходному коду. Doxygen специально для таких случаев может генерировать документацию в формате XML.

Генератор документации на основе шаблонов документов создает LaTeX документы, которые уже в PDF формате передаются заказчику.

Автоматизация оформления документации - 2

Диаграмма создания документации

Руководитель --> (Планы)
Руководитель -> (Требования)
Руководитель -> (Описание тестов)
Руководитель --> (Обнаруженные проблемы)
(Требования) -> Программисты
Программисты --> (Программный код)
(Программный код) --> Doxygen
Doxygen --> (Описание реализации)

(Шаблоны документов) -->: Генератор документации:: LaTeX

(Требования) -->: Генератор документации:: CSV
(Планы) -->: Генератор документации:: LaTeX
(Описание реализации) -->: Генератор документации:: XML
(Описание тестов) -->: Генератор документации:: XML
(Обнаруженные проблемы) -->: Генератор документации:: CSV

: Генератор документации: --> (Комплект документации): LaTeX

Генератор документации

Для реализации такой системы создания документации мне потребовалась утилита обработки шаблонов и скрипт сборки.

Скрипт сборки я реализовал в Makefile. Скрипт выполнял следующие действия:

  • Получал исходники
  • Генерировал XML описания с помощью Doxygen
  • Собирал все необходимые документы из шаблонов с помощью pytemplate.py
  • Генерировал PDF-ки LaTeX-ом
  • Формировал дерево папок и создавал образ диска для записи
  • формировал необходимую сопроводительную документацию (файл с титульными листами, этикетку диска)

Автоматизация оформления документации - 3

Диаграмма последовательности генерации документации

GIT->«Генератор документации»: Исходные тексты
«Генератор документации»->Doxygen: Исходные тексты
Doxygen->«Генератор документации»: XML описание
«Данные проекта»->«Генератор документации»: Шаблоны
«Генератор документации»->PyTemplate: Шаблоны
«Данные проекта» -> PyTemplate: CSV, XML
PyTemplate->LaTeX: LaTeX документы
LaTeX->«Генератор документации»: PDF документы

Ключевой элемент системы — утилита обработки шаблонов документов.

Утилита обработки шаблонов

Исходные коды можно получить: github.com/krotos139/pytemplate

Или установить утилиту можно с помощью команды:

sudo pip install pytemplateproc

Использование утилиты: pytemplate.py [options]
Опции:

  • --version Отобразить версию
  • -h, --help Отобразить информацию о ключах запуска
  • -t TEMPLATE, --template=TEMPLATE Указать путь до файла шаблона
  • -o OUTPUT, --output=OUTPUT Указать путь до выходного файла
  • -f FORMAT, --format=FORMAT Формат файла шаблона, может принимать значения (odt и text)
  • -a ARG, --arg=ARG Дополнительная сущность для шаблона

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

Поддерживаемые источники данных:

  • CSV таблица (Может быть отредактирована в Exel при соблюдении определенных правил)
  • XML документ
  • Текстовый файл
  • SQLite база данных
  • Функция MD5 от файла
  • Функция получения данных о файле

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

Пример шаблона:

{%- set docs = load_csv("database2.csv")  %}
subsection{Список документов}

begin{longtable}{|m{2cm}|m{3cm}|m{3cm}|m{3cm}|m{3cm}|}
caption{Списки документов} label{tab:reports}\hline
{centering Код} \hline
endfirsthead
caption*{it{Продолжение таблицы} ref{tab:reports}}\hline
{centering Код} \hline
endhead
{%- for item in docs %}
{{ item.id }} } } } } \hline
{%- endfor %}
end{longtable}
newpage

Заключение

Использование утилиты pytemplate позволяет создавать документы и отчеты по шаблонам, используя для заполнения шаблонов данные. При этом данные можно хранить в удобном формате электронных таблиц или баз данных.

Автор: krotos139

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js